refactor(mcp-server): extract framework-agnostic handlers

[Scra3]

Summary

• Extract framework-agnostic McpHandlers class from Express-based MCP server
• Agent now creates native Koa routes using the handlers instead of bridging Express middleware
• Remove express-to-koa.ts utility (no longer needed)
• Add getAuthorizationUrl() method to ForestOAuthProvider for framework-agnostic authorization

Architecture

The @forestadmin/mcp-server package now exports:

• McpHandlers: Framework-agnostic class that returns data/results instead of manipulating response objects
• ForestMCPServer: Express-based server (kept for CLI/standalone usage)

The agent creates native Koa routes that use McpHandlers:

// In agent.ts
const handlers = new McpHandlers(options);
await handlers.initialize();

router.get('/.well-known/oauth-authorization-server', ctx => {
  ctx.body = handlers.getOAuthMetadata(baseUrl);
});

router.post('/oauth/authorize', async ctx => {
  const result = await handlers.handleAuthorize(params);
  if (result.type === 'redirect') ctx.redirect(result.url);
});

Benefits

• No Express-to-Koa bridging needed
• Cleaner separation of concerns (handlers vs HTTP layer)
• Framework-agnostic handlers can be reused with any HTTP framework
• Native Koa integration in agent

Test plan

• All unit tests pass (yarn test)
• Build passes (yarn build)
• Lint passes

🤖 Generated with Claude Code

[qltysh]

14 new issues

Tool	Category	Rule	Count
qlty	Structure	Function with high complexity (count = 19): useCallbackOnFastify	5
qlty	Structure	Function with many returns (count = 4): handleAuthorize	4
qlty	Structure	Function with many parameters (count = 4): exchangeAuthorizationCode	3
qlty	Structure	Deeply nested control flow (level = 4)	2