@typescape-ai/mcp

Typescape MCP Server — Model Context Protocol integration for AI agents (Claude, Cursor, Windsurf, etc.).

Exposes 32 tools for session management, thread/comment workflows, review references, approval, quality gates, corpus intelligence, and steering governance.

Requirements

• Bun >= 1.0.0

Installation

bun add -D @typescape-ai/mcp

Usage with Claude Code

Add to your Claude Code MCP settings (~/.claude/mcp.json):

{
  "mcpServers": {
    "typescape": {
      "command": "bunx",
      "args": ["@typescape-ai/mcp"],
      "env": {
        "TYPESCAPE_API_KEY": "your-token-here",
        "TYPESCAPE_BASE_URL": "https://your-typescape-instance.vercel.app"
      }
    }
  }
}

Usage with Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "typescape": {
      "command": "bunx",
      "args": ["@typescape-ai/mcp"],
      "env": {
        "TYPESCAPE_API_KEY": "your-token-here",
        "TYPESCAPE_BASE_URL": "https://your-typescape-instance.vercel.app"
      }
    }
  }
}

Then reload MCP servers in Cursor (Cmd+Shift+P > "MCP: Reload").

Quick Start Workflow

The typical 4-step happy path for an agent:

1. Create a review session

// typescape_create_session
{
  "repo_id": "my-org/my-repo",
  "git_sha": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
  "file_path": "docs/README.md",
  "participants": [{ "email": "reviewer@example.com", "roles": ["reviewer"] }]
}


// → { "session_id": "sess_01HX...", "invitations": [...] }

2. Get rendered blocks for anchoring

// typescape_get_render
{ "session_id": "sess_01HX..." }


// → { "blocks": [{ "block_id": "blk_...", "type": "paragraph", "html": "..." }, ...] }

3. Create a thread on a specific block

// typescape_create_thread
{
  "session_id": "sess_01HX...",
  "block_id": "blk_...",
  "body": "This section could be clearer about error handling.",
  "severity": "suggestion"
}


// → { "thread_id": "thr_...", "comment_id": "cmt_..." }

4. Export structured feedback

// typescape_export_feedback
{ "session_id": "sess_01HX..." }


// → { "schema_version": "v1", "session": {...}, "threads": [...], "comments": [...] }

Tool Catalog

Session Lifecycle

Threads & Comments

Review References

Review Sets

Approval

Note: Approvals are human decisions. MCP can request approval and read status, but approval decisions must be submitted through the reviewer portal.

Quality Gates

Corpus Intelligence

Steering Governance

Output Conventions

typescape_create_session Input Modes

typescape_create_session supports two mutually exclusive creation modes:

1. git-backed: provide repo_id, git_sha, and file_path
2. inline: provide content_body and file_path, plus optional inline_assets (path -> base64)

inline_assets constraints:

• Paths must be relative (no leading /, no .. traversal segments)
• Values must be valid base64 strings
• Total decoded payload must be <= 10MB (inline_payload_too_large otherwise)

Optional forward-compatible field:

• document_type (currently only "markdown"; default "markdown")

All tool responses return JSON in content[0].text:

{
  "content": [
    { "type": "text", "text": "{\"session_id\": \"sess_01HX...\", ...}" }
  ]
}

Every response includes a request_id for support triage.

Error shape:

{
  "error": {
    "code": "session_not_found",
    "message": "No session with ID sess_01HX...",
    "retryable": false,
    "request_id": "req_abc123"
  }
}

Common error codes: session_not_found, invalid_block_id, unauthorized, rate_limited, feature_disabled.

Feature Gates Summary

Tools without a feature gate are always available when the MCP server is running.

When a gated tool is called without its feature enabled, it returns:

{
  "error": {
    "code": "feature_disabled",
    "message": "Feature 'steering' is not enabled"
  }
}

Environment Variables

License

MIT