[WIP] Feat: Native + MCP Tool Router with helper methods

[haxzie]

Note

Introduce a first-class Tool Router that creates isolated sessions, wraps tools per provider, exposes authorize/connection helpers, and adds SDK APIs and examples in both Python and TypeScript.

• Python:
  • New Tool Router: Implement composio.core.models.tool_router.ToolRouter providing create() to open isolated MCP-backed sessions returning {session_id, mcp, tools(), authorize(), connections()}.
  • Experimental Kept: Move previous API to tool_router_experimental.py and expose under composio.experimental.tool_router.
  • SDK Wiring: Composio now exposes tool_router and experimental.create (proxy to stable ToolRouter.create).
  • Utils: Add utils.uuid with generate_uuid/generate_short_id and export via utils.__init__.
  • Examples: Add basic/advanced Tool Router examples and an agent demo using session tools.
• TypeScript:
  • Stable Tool Router: Add models/ToolRouter with create() returning session {sessionId, mcp, tools(), authorize(), toolkits()}; new rich config/types in types/toolRouter.types.
  • Experimental API: Retain prior API under models/ToolRouter.experimental with types moved to toolRouter.experimental.types.
  • SDK Updates: Composio now exposes toolRouter and experimental.create() (delegates to stable). Export paths updated.
  • Tools Refactor: Tools constructed without direct provider arg and adds wrapToolsForProvider(); internal calls updated.
  • Examples: Add ts/examples/tool-router and simplify Vercel example stream setup.
  • Misc: Lockfile and deps updated (e.g., @ai-sdk/[email protected], ora, etc.).

^{Written by Cursor Bugbot for commit decd89f. This will update automatically on new commits. Configure here.}

[cursor]

Bug: Cross-language tool inconsistency.

The TypeScript tool router excludes COMPOSIO_REMOTE_BASH_TOOL from the default tool list, while the Python implementation includes it. This cross-language inconsistency means sessions created via TypeScript vs Python will have different available tools, potentially breaking feature parity.

 

[macroscopeapp]

Add provider-aware ToolRouter.create returning ToolRouterSession with MCP config in Python and TypeScript SDKs to introduce native + MCP tool routing with helper methods

Introduce a new provider-aware tool router that exposes Composio.tool_router.create (Python) and composio.toolRouter.create (TypeScript) returning a ToolRouterSession with mcp, tools(), authorize(), and connection state helpers, and update Tools to wrap execution for the configured provider while preserving the legacy experimental router under experimental.tool_router.

📍Where to Start

Start with the TypeScript implementation in ToolRouter.ts, then review the Python counterpart in tool_router.py and how it is wired in sdk.py.

---

Macroscope summarized decd89f.

[macroscopeapp]

__getitem__ claims dict-style access but uses getattr, which raises AttributeError on missing keys. Consider raising KeyError instead to match dict semantics (e.g., check hasattr and raise KeyError).

Suggested change

	return getattr(self, key)
	if hasattr(self, key):
	return getattr(self, key)
	raise KeyError(key)

🚀 Reply to ask Macroscope to explain or update this suggestion.

👍 Helpful? React to give us feedback.

[macroscopeapp]

Issue on line in ts/packages/core/src/composio.ts:221:

Tools/ToolRouter read config.provider, but the default provider isn’t synced into this.config, causing ComposioProviderNotDefinedError when none is passed. Suggest syncing: set this.config.provider = this.provider before constructing (or pass provider explicitly).

       this.provider = (config?.provider ?? new OpenAIProvider()) as TProvider;
+      this.config.provider = this.provider;
 
       const defaultHeaders = getDefaultHeaders(this.config.defaultHeaders, this.provider);

🚀 Reply to ask Macroscope to explain or update this suggestion.

👍 Helpful? React to give us feedback.

[macroscopeapp]

ToolRouter.__init__ only accepts client, but callers pass provider too. This will raise TypeError. Consider accepting an optional provider arg (and ignore or store it) to keep parity with existing usage.

Suggested change

	def __init__(self, client: HttpClient):
	def __init__(self, client: HttpClient, provider: t.Optional[object] = None):

🚀 Reply to ask Macroscope to explain or update this suggestion.

👍 Helpful? React to give us feedback.

[cursor]

Bug: ToolRouter: Essential Types Not Exported

The export statement was changed from ./types/toolRouter.types to ./types/toolRouter.experimental.types, which removes the new types like ToolRouterConfig, ToolRouterSession, MCPServerType, ToolRouterMCPServerConfig, ToolRouterAuthorizeFn, ToolRouterToolkitsFn, etc. from the public API. These types are used by composio.ts and are part of the new ToolRouter feature, so they need to be exported for external consumers.

 

[macroscopeapp]

auth_configs and connected_accounts are accepted in ToolRouter.create(...) but never used. Consider wiring these through to the backend/session (e.g., include them in the API request or persist them on ToolRouterSession) so the user’s auth context and account selection aren’t silently dropped; otherwise consider documenting or removing these args for now.

🚀 Reply to ask Macroscope to explain or update this suggestion.

👍 Helpful? React to give us feedback.

[cursor]

Bug: Tools: Missing dependency causes runtime errors.

The ToolsModel is instantiated with provider=self._provider, but self._provider can be None since it's declared as t.Optional[TProvider] in the constructor. The Python Tools class requires a non-None provider and will fail when attempting to wrap tools or execute operations that depend on the provider.