Type MCP tools/list responses in OpenAPI and the generated SDK

[lamenting-hawthorn]

Problem

GET /api/v1/mcp-servers/{name}/tools currently documents every MCP tool as an untyped Record<string, unknown>. Generated OpenAPI and SDK consumers therefore cannot discover standard MCP tool fields such as the name, description, input/output JSON schemas, annotations, icons, or execution metadata.

The route already contains a TODO to type this response.

Proposed scope

• Add named, reusable Zod/OpenAPI schemas for the MCP tool wire shape.
• Preserve MCP-designated _meta, nested JSON Schema extension fields, and TrueForge's existing preload hint.
• Use the typed item schema in ListMcpServerToolsResponse.
• Regenerate the committed OpenAPI documents and TypeScript SDK through the repository generator.
• Add contract tests for representative tool metadata and the production route.

Expected behavior

The endpoint path and response envelope remain unchanged, while OpenAPI and generated SDK clients expose standard MCP tool fields as typed properties. The generated TypeScript SDK follows its normal naming convention by exposing wire _meta as meta; its serializer continues to read and write _meta on the HTTP wire.

Non-goals

• Preserving arbitrary unknown top-level tool properties that the upstream MCP SDK does not retain.
• Changing MCP tool execution behavior.
• Changing approval policy.
• Hand-editing generated OpenAPI or SDK files.

[lamenting-hawthorn]

I'd like to take this on and have a working implementation ready to review.

Proposed approach (implemented):

• Add a named, reusable McpTool Zod/OpenAPI schema in packages/trueforge/src/schemas/mcpTool.ts modeling the MCP Tool wire shape: name, title, description, inputSchema/outputSchema (JSON Schema), annotations, execution, icons, TrueForge's preload hint, and MCP-designated _meta.
• Use z.object(...).loose() (zod 4, avoids deprecated passthrough) so unknown JSON Schema extension fields and _meta pass through on the wire, matching the issue's scope.
• ListMcpServerToolsResponse.data becomes McpTool[]; the route handler parses each tool through McpToolSchema to enforce the typed contract.
• Regenerated openapi.json (both copies) and packages/trueforge-sdk via pnpm openapi:write + pnpm sdk:generate — SDK exposes wire _meta as meta, serializer keeps _meta on the wire.
• Added tests/unit/schemas/mcpTool.test.ts (8 contract tests) + the regenerated Fern SDK wire test.

Verification: pnpm build, pnpm test, pnpm typecheck, pnpm lint:ci (trueforge + trueforge-sdk clean), pnpm format:check all pass. OpenAPI uses plain $ref (no allOf), flat objects per repo conventions.

One blocker: the implementation is on my fork (lamenting-hawthorn/trueforge, branch feat/type-mcp-tools), but GitHub is rejecting POST /repos/truefoundry/trueforge/pulls with does not have the correct permissions to execute CreatePullRequest (GraphQL) / 404 (REST), even though the fork is valid and PRs are enabled on the repo. If you'd like me to open the PR, could you let me know if there's an org setting that restricts fork PR creation, or would you prefer I apply the same change and you open the PR from it? Happy to adjust the approach if you'd prefer a different schema shape.