Skip to content

model-context-protocol-integration.md

Latest commit

 

History

History
39 lines (26 loc) · 3.29 KB

model-context-protocol-integration.md

File metadata and controls

39 lines (26 loc) · 3.29 KB
Raw

Model Context Protocol (MCP) integration

Status: roadmap. There is no MCP code in this repository today. This page records the design direction for the "MCP tool packaging" roadmap item: how forge's existing tool contracts map onto MCP tool definitions, and what a packaging target would emit. It is a design note, not feature documentation.

Why MCP is a natural packaging target

MCP servers expose tools as { name, description, inputSchema } where inputSchema is JSON Schema. Forge's tools.json (see tool-calling-skill-contracts.md) already carries exactly that shape, plus safety metadata MCP can express through tool annotations. No semantic translation is needed — only projection.

Proposed mapping

forge tools.json field MCP tool field
name name
description description
inputSchema inputSchema (already JSON-Schema-shaped)
type: "read" annotations.readOnlyHint: true
type: "write" annotations.readOnlyHint: false, annotations.destructiveHint per non-goals
idempotent: true annotations.idempotentHint: true
requiresConfirmation: true no direct MCP equivalent — see below

Confirmation honesty note: MCP annotations are hints; the protocol has no enforced user-confirmation flag, and hosts decide their own approval UX. The forge contract survives anyway because confirmation is encoded in the schema: a gated tool requires user_confirmed: true as an input property, so a host that ignores hints still cannot form a valid call without it. The projection would keep that property and additionally prepend the confirmation rule to the tool description.

What the packaging target would emit

Planned deliverable for a --package-format mcp mode (tracked in roadmap.md):

  1. mcp-tools.json — the projected tool list, ready to be served by any MCP server implementation.
  2. Optionally, a minimal server scaffold (TypeScript, stdio transport) that registers the projected tools and fails each call with "not implemented" — because forge defines tool contracts, not tool backends. Wiring create_event to a real calendar API is and will remain the integrator's code.
  3. A verification rule set for the projection: every requirement tool present, schemas valid JSON Schema, read/write hints consistent with tool type, confirmation-gated tools carrying the user_confirmed property. This keeps the same quality-gate philosophy: the MCP surface would be verified before it is packaged.

What this integration will not do

  • It will not implement tool business logic or connect to providers.
  • It will not replace SKILL.md: MCP describes the callable surface; the skill instructions still govern when and how an agent should call it.
  • It will not weaken safety metadata to fit the protocol — where MCP cannot enforce a rule (confirmation), the rule stays enforced at the schema level and documented in the description.

Extension seam

When implemented, the projection belongs next to the existing packagers: a pure function from ToolDefinition[] (src/core/types.ts) to MCP tool JSON, invoked from src/packaging/package-builder.ts, with its own zod schema in verification. Contributions welcome once the roadmap item opens.