Add MCP server for TypeSpec docs and API signatures

[swatkatz]

Summary

• Adds packages/mcp-server-typespec-docs, a local MCP server that exposes TypeSpec documentation and compiler API signatures to agents
• Three tools: search_docs (full-text search), get_doc (fetch by path), get_type_signature (compiler API lookup)
• Reads from local repo when available, falls back to fetching from GitHub for users who don't have pinterest/typespec cloned
• Built with @modelcontextprotocol/sdk + minisearch (fuzzy full-text search)

Usage

If you have pinterest/typespec cloned:

cd packages/mcp-server-typespec-docs && npm install && npm run build

Add to .mcp.json:

"typespec-docs": {
  "type": "stdio",
  "command": "node",
  "args": ["<path-to-repo>/packages/mcp-server-typespec-docs/dist/server.js"]
}

If you don't have it cloned (e.g. working in pinboard): the server fetches docs from raw.githubusercontent.com/pinterest/typespec/main/ on first query and caches for the session.

Tools

Tool	Description
search_docs(query, [topic])	Full-text search across all TypeSpec docs (language basics, extending-typespec, libraries, emitters, etc.)
get_doc(path)	Fetch a specific doc page by relative path
get_type_signature(symbol)	Look up TypeSpec compiler API type definitions + JSDoc (e.g. Realm, Model, mutateSubgraph)

Test plan

• Server responds to MCP initialize handshake
• search_docs("decorators", topic: "language-basics") returns decorators doc
• search_docs("emitter framework") returns extending-typespec docs
• get_doc("extending-typespec/create-decorators.md") returns full page
• get_type_signature("Realm") returns class definition with JSDoc
• get_type_signature("Model") returns correct interface from core/types.ts
• Prettier + ESLint pass (monorepo config)
• GitHub fallback (needs testing outside repo clone)

🤖 Generated with Claude Code