Package Exports

@typescape-ai/mcp

Readme

@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

Tool	Description
`typescape_create_session`	Create a review session for a Markdown file. Returns session ID and invitations. Agent must provide a concrete 40-hex Git SHA.
`typescape_supersede_session`	Create a new session pinned to a newer revision, superseding an existing session. The predecessor becomes read-only and unresolved threads carry forward.
`typescape_list_sessions`	List sessions with optional filters (repo, status, file path). Returns paginated summaries.
`typescape_get_session`	Get full session metadata including participants, stats, and provenance.
`typescape_get_render`	Get rendered content with immutable block-level HTML structure and `block_id`s for anchoring.
`typescape_export_feedback`	Export all feedback as structured JSON (schema v1) including threads, comments, and anchors.
`typescape_export_response_matrix`	Export per-thread disposition and evidence summary.

Threads & Comments

Tool	Description
`typescape_get_threads`	List threads for a session. Optionally filter by `block_id` or status. Returns paginated list with comments.
`typescape_create_thread`	Create a new thread on a block. Agent-created threads are tagged `source='automation'`.
`typescape_post_comment`	Post a reply to an existing thread.
`typescape_resolve_thread`	Resolve (close) a thread. Optionally include a disposition. Supports optimistic concurrency via `expected_version`.
`typescape_reopen_thread`	Reopen a previously resolved thread. Supports optimistic concurrency.
`typescape_record_disposition`	Record a disposition (decision) on a thread. A resolving disposition may auto-resolve the thread.
`typescape_attach_evidence`	Attach evidence to a thread (commit SHA, proposed change, PR URL, attestation, external ticket, or note).

Review References

Tool	Description
`typescape_create_review_ref`	Create a stable review reference that tracks the HEAD session for doc/file/PR/custom keys. Always available (core primitive).
`typescape_resolve_review_ref`	Resolve a review ref to its current head session ID and pinned content details.
`typescape_advance_review_ref`	Advance a review ref to a new head session. Supports optimistic concurrency via `expected_head_session_id`.

Review Sets

Tool	Description	Feature Gate
`typescape_create_review_set`	Create a multi-file review pack.	`features.review_sets`
`typescape_export_review_set`	Export feedback from a review set.	`features.review_sets`

Approval

Tool	Description
`typescape_request_approval`	Request approval for a session from specified approvers. Sends notifications via configured channels.

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

Quality Gates

Tool	Description	Feature Gate
`typescape_get_status`	Get the policy verdict for a session (pass/fail/needs_review with reasons).	`features.policy`
`typescape_run_checks`	Trigger quality checks (DocLint-as-Threads) for a session. Returns the check run ID.	`features.checks`

Corpus Intelligence

Tool	Description	Feature Gate
`typescape_get_snapshot`	Get corpus snapshot metadata for a repo at a specific commit.	`features.corpus_snapshots`
`typescape_list_backlinks`	List inbound backlinks for a target file within a corpus snapshot.	`features.corpus_snapshots`
`typescape_get_impact`	Compute the impact radius for a session — which other files are affected via backlinks.	`features.corpus_snapshots`
`typescape_get_steering`	Get active steering rules for a repository. Supports `structured` (authoritative) and `prompt_fragment` (pre-computed text) formats.	`features.steering`

Steering Governance

Tool	Description	Feature Gate
`typescape_create_gci`	Create a guideline change item from observed patterns, thread feedback, or automated analysis.	`features.steering`
`typescape_list_gcis`	List guideline change items filtered by status.	`features.steering`
`typescape_list_proposals`	List steering rule proposals awaiting operator approval.	`features.steering`
`typescape_steering_dashboard`	Get aggregate steering health: active rule count, average health, degraded rules.	`features.steering`
`typescape_promote_gci`	Convert an approved GCI into a steering proposal for operator acceptance.	`features.steering`
`typescape_decide_proposal`	Accept, reject, or deprecate a steering proposal. Accepting activates the rule immediately.	`features.steering`

Output Conventions

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

Feature Flag	Tools Gated
`features.review_sets`	`create_review_set`, `export_review_set`
`features.policy`	`get_status`
`features.checks`	`run_checks`
`features.corpus_snapshots`	`get_snapshot`, `list_backlinks`, `get_impact`
`features.steering`	`get_steering`, `create_gci`, `list_gcis`, `list_proposals`, `steering_dashboard`, `promote_gci`, `decide_proposal`

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

Variable	Required	Description
`TYPESCAPE_API_KEY`	Yes	Operator API token
`TYPESCAPE_BASE_URL`	Yes	Typescape server URL

License

MIT