Documentation
¶
Overview ¶
Package mcp implements a Model Context Protocol (MCP) server for ctx.
MCP is a standard protocol (JSON-RPC 2.0 over stdin/stdout) that allows AI tools to discover and consume context from external sources. This package exposes ctx's context files as MCP resources and ctx commands as MCP tools, enabling any MCP-compatible AI tool (Claude Desktop, Cursor, Windsurf, VS Code Copilot, etc.) to access project context without tool-specific integrations.
Architecture ¶
AI Tool → stdin → MCP Server → ctx internals AI Tool ← stdout ← MCP Server ← ctx internals
The server communicates via JSON-RPC 2.0 over stdin/stdout.
Resources ¶
Resources expose context files as read-only content:
ctx://context/tasks → TASKS.md ctx://context/decisions → DECISIONS.md ctx://context/conventions → CONVENTIONS.md ctx://context/constitution → CONSTITUTION.md ctx://context/architecture → ARCHITECTURE.md ctx://context/learnings → LEARNINGS.md ctx://context/glossary → GLOSSARY.md ctx://context/agent → All files assembled in read order
Tools ¶
Tools expose ctx commands as callable operations:
ctx_status → Context health summary ctx_add → Add a task, decision, learning, or convention ctx_complete → Mark a task as done ctx_drift → Detect stale or invalid context ctx_recall → Query past session history ctx_watch_update → Apply structured context updates to files ctx_compact → Move completed tasks to archive ctx_next → Get the next pending task ctx_check_task_completion → Nudge when a recent action may complete a task ctx_session_event → Signal session start/end lifecycle ctx_remind → List active reminders
Prompts ¶
Prompts provide pre-built templates for common workflows:
ctx-session-start → Load full context at session start ctx-add-decision → Format an architectural decision entry ctx-add-learning → Format a learning entry ctx-reflect → Guide end-of-session reflection ctx-checkpoint → Report session statistics
Usage ¶
server := mcp.NewServer(contextDir, version) server.Serve() // blocks, reads stdin, writes stdout
Design Invariants ¶
This implementation preserves all six ctx design invariants:
- Markdown-on-filesystem: all state remains in .context/ files
- Zero runtime dependencies: no external services required
- Deterministic assembly: same files + budget = same output
- Human authority: tools propose changes through file writes
- Local-first: no network required for core operation
- No telemetry: no data leaves the local machine
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package handler contains domain logic for MCP tool operations.
|
Package handler contains domain logic for MCP tool operations. |
|
task
Package task iterates pending tasks from TASKS.md for MCP tool responses.
|
Package task iterates pending tasks from TASKS.md for MCP tool responses. |
|
Package proto defines JSON-RPC 2.0 message types and MCP protocol constants for the ctx MCP server.
|
Package proto defines JSON-RPC 2.0 message types and MCP protocol constants for the ctx MCP server. |
|
Package server implements the MCP server that exposes ctx context files as resources, tools, and prompts over JSON-RPC 2.0 on stdin/stdout.
|
Package server implements the MCP server that exposes ctx context files as resources, tools, and prompts over JSON-RPC 2.0 on stdin/stdout. |
|
catalog
Package catalog maps context files to MCP resource URIs and builds the immutable resource list returned by the server.
|
Package catalog maps context files to MCP resource URIs and builds the immutable resource list returned by the server. |
|
def/prompt
Package prompt defines MCP prompt definitions and entry builders.
|
Package prompt defines MCP prompt definitions and entry builders. |
|
def/tool
Package tool defines MCP tool definitions and shared property builders.
|
Package tool defines MCP tool definitions and shared property builders. |
|
dispatch
Package dispatch routes MCP requests to domain-specific handlers based on method name.
|
Package dispatch routes MCP requests to domain-specific handlers based on method name. |
|
extract
Package extract converts raw MCP tool arguments into typed Go values.
|
Package extract converts raw MCP tool arguments into typed Go values. |
|
io
Package io writes serialized JSON-RPC messages to an io.Writer with mutex-guarded concurrency.
|
Package io writes serialized JSON-RPC messages to an io.Writer with mutex-guarded concurrency. |
|
out
Package out builds JSON-RPC response structs for success, error, and tool result payloads.
|
Package out builds JSON-RPC response structs for success, error, and tool result payloads. |
|
parse
Package parse unmarshals raw JSON bytes into MCP request structs, filtering out notifications.
|
Package parse unmarshals raw JSON bytes into MCP request structs, filtering out notifications. |
|
ping
Package ping responds to MCP ping requests with an empty success result.
|
Package ping responds to MCP ping requests with an empty success result. |
|
poll
Package poll watches subscribed resources for file changes and emits update notifications.
|
Package poll watches subscribed resources for file changes and emits update notifications. |
|
resource
Package resource handles MCP resource requests including list, read, subscribe, and unsubscribe.
|
Package resource handles MCP resource requests including list, read, subscribe, and unsubscribe. |
|
route/fallback
Package fallback returns method-not-found errors for unrecognized MCP methods.
|
Package fallback returns method-not-found errors for unrecognized MCP methods. |
|
route/initialize
Package initialize handles the MCP initialize handshake and advertises server capabilities.
|
Package initialize handles the MCP initialize handshake and advertises server capabilities. |
|
route/prompt
Package prompt dispatches MCP prompt list and get requests to the appropriate builders.
|
Package prompt dispatches MCP prompt list and get requests to the appropriate builders. |
|
route/tool
Package tool dispatches MCP tool list and call requests to the appropriate handler functions.
|
Package tool dispatches MCP tool list and call requests to the appropriate handler functions. |
|
stat
Package stat provides session statistics helpers for the MCP server.
|
Package stat provides session statistics helpers for the MCP server. |
|
Package session tracks advisory state for an MCP server session, including tool call counts, entry adds, and pending updates.
|
Package session tracks advisory state for an MCP server session, including tool call counts, entry adds, and pending updates. |
Click to show internal directories.
Click to hide internal directories.