feat: support oauth2 protected mcp servers

[mKeRix]

This change will allow toolscript to be used with MCP servers that require authentication via oauth2, specifically via the authorization code flow with dynamic client registration.

[gemini-code-assist]

Summary of Changes

Hello @mKeRix, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances Toolscript's capabilities by integrating robust OAuth2 authentication for HTTP and SSE MCP servers. The primary goal is to enable seamless interaction with modern, protected APIs by providing a user-friendly CLI command for interactive authorization and automatic handling of token lifecycle. The changes are designed to be additive, ensuring backward compatibility while introducing a secure and efficient authentication mechanism.

Highlights

• OAuth2 Authentication Support: Toolscript now supports OAuth2 authentication for HTTP and SSE-based MCP servers, enabling connections to protected APIs using standard flows like Authorization Code and Client Credentials.
• New toolscript auth CLI Command: A new command, toolscript auth <server-name>, has been introduced to facilitate interactive OAuth2 authentication. This command guides users through the authorization process, including opening a browser for consent and securely storing credentials.
• Dynamic Client Registration & OAuth Discovery: The system leverages OAuth discovery to automatically configure authentication endpoints and supports dynamic client registration (RFC 7591), minimizing manual configuration for users.
• Secure Credential Storage: OAuth credentials (client information and tokens) are now securely stored in a file-based system (~/.toolscript/oauth/<server-name>.json) with restricted permissions (0600 for files, 0700 for directories) to protect sensitive data.
• Automatic Token Management: The underlying MCP SDK automatically handles token refresh and retry mechanisms, ensuring continuous access to protected resources without requiring manual re-authentication until the refresh token expires or is revoked.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[codecov-commenter]

Codecov Report

❌ Patch coverage is 47.14286% with 333 lines in your changes missing coverage. Please review.
✅ Project coverage is 52.34%. Comparing base (80ea0d9) to head (0447aa6).
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
src/cli/commands/auth.ts	21.02%	154 Missing ⚠️
src/gateway/mcp-utils.ts	9.56%	104 Missing ⚠️
src/oauth/browser.ts	6.25%	30 Missing ⚠️
src/gateway/mcp-client.ts	20.00%	20 Missing ⚠️
src/gateway/aggregator.ts	23.80%	16 Missing ⚠️
src/oauth/storage.ts	88.00%	9 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main       #3      +/-   ##
==========================================
- Coverage   52.83%   52.34%   -0.50%     
==========================================
  Files          25       32       +7     
  Lines        1709     2279     +570     
  Branches      105      136      +31     
==========================================
+ Hits          903     1193     +290     
- Misses        806     1086     +280     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[gemini-code-assist]

Code Review

This pull request introduces a significant and well-architected feature to support OAuth2-protected MCP servers. The changes are extensive, including a new toolscript auth command for handling the Authorization Code flow, persistent token storage, and integration with the MCP SDK's OAuth capabilities. The code is well-structured, with good separation of concerns into new modules for OAuth providers, storage, and utilities. The addition of comprehensive unit, integration, and E2E tests is commendable.

However, I've identified a critical bug in the toolscript auth command's implementation that prevents the Authorization Code flow from completing successfully due to incorrect state management of the OAuth provider. I've also noted a discrepancy where the documentation and design files mention support for the Client Credentials flow, but the implementation for it appears to be missing.

Once these issues are addressed, this will be an excellent addition to the project.

[mKeRix]

/gemini review

[gemini-code-assist]

Code Review

This is a comprehensive pull request that adds significant new functionality for OAuth2 authentication. The changes are well-structured, with new logic organized into a dedicated oauth module, a new auth CLI command, and necessary updates to the gateway. The implementation smartly leverages the MCP SDK's capabilities, focusing on providing a persistent storage layer and a user-friendly command-line flow. The inclusion of detailed design documents and extensive tests (unit, integration, and E2E) is commendable. I've identified a couple of minor areas for improvement: a typo in a log message and some redundant code that can be cleaned up for better clarity. Overall, this is an excellent and well-executed feature.

[github-actions]

🎉 This PR is included in version 1.0.0 🎉

The release is available on:

• JSR.io
• GitHub release

Your semantic-release bot 📦🚀