feat: add MCP server for tool-agnostic AI integration

.context/ARCHITECTURE.md

@@ -51,7 +51,7 @@ upward from them. The `rc` package mediates config resolution;
 | `internal/crypto`  | AES-256-GCM encryption (stdlib only)            | `Encrypt()`, `Decrypt()`, `GenerateKey()`         |
 | `internal/sysinfo` | OS metrics with platform build tags             | `Collect()`, `Evaluate()`, `MaxSeverity()`        |
 
-<!-- drift-check: ls -d internal/rc internal/context internal/drift internal/index internal/task internal/validation internal/recall/parser internal/claude internal/notify internal/journal/state 2>/dev/null | wc -l -->
+<!-- drift-check: ls -d internal/rc internal/context internal/drift internal/index internal/task internal/validation internal/recall/parser internal/claude internal/notify internal/journal/state internal/mcp internal/eventlog 2>/dev/null | wc -l -->
 ### Core Packages
 
 | Package                  | Purpose                                                | Key Exports                                |
@@ -66,6 +66,8 @@ upward from them. The `rc` package mediates config resolution;
 | `internal/claude`        | Claude Code integration types and skill access         | `Skills()`, `SkillContent()`               |
 | `internal/notify`        | Webhook notifications with encrypted URL storage       | `Send()`, `LoadWebhook()`, `SaveWebhook()` |
 | `internal/journal/state` | Journal processing pipeline state (JSON)               | `Load()`, `Save()`, `Mark*()`              |
+| `internal/mcp`           | MCP server (JSON-RPC 2.0 over stdin/stdout)            | `NewServer()`, `Serve()`                   |
+| `internal/eventlog`      | Append-only JSONL event logging for hook diagnostics   | `Append()`, `Rotate()`                     |
 
 <!-- drift-check: ls -d internal/cli/*/ | wc -l -->
 ### Entry Point
@@ -103,6 +105,7 @@ upward from them. The `rc` package mediates config resolution;
 | `system`      | System diagnostics, resource monitoring, hook plumbing                          |
 | `task`        | Task archival and snapshots                                                     |
 | `watch`       | Monitor stdin for context-update tags and apply them                            |
+| `mcp`         | MCP server for AI tool integration (stdin/stdout JSON-RPC)                      |
 
 ## Data Flow Diagrams
 

docs/cli/index.md

@@ -76,6 +76,7 @@ own guards and no-op gracefully.
 | [`ctx why`](tools.md#ctx-why)                   | Read the philosophy behind ctx                         |
 | [`ctx site`](tools.md#ctx-site)                 | Site management (feed generation)                      |
 | [`ctx doctor`](doctor.md#ctx-doctor)            | Structural health check (hooks, drift, config)         |
+| [`ctx mcp`](mcp.md#ctx-mcp)                    | MCP server for AI tool integration (stdin/stdout)      |
 | [`ctx config`](config.md#ctx-config)            | Manage runtime configuration profiles                  |
 | [`ctx system`](system.md#ctx-system)            | System diagnostics and hook commands                   |
 

docs/cli/mcp.md

@@ -0,0 +1,165 @@
+---
+#   /    ctx:                         https://ctx.ist
+# ,'`./    do you remember?
+# `.,'\
+#   \    Copyright 2026-present Context contributors.
+#                 SPDX-License-Identifier: Apache-2.0
+
+title: MCP Server
+icon: lucide/plug
+---
+
+## `ctx mcp`
+
+Run ctx as a [Model Context Protocol](https://modelcontextprotocol.io)
+(MCP) server. MCP is a standard protocol that lets AI tools discover
+and consume context from external sources via JSON-RPC 2.0 over
+stdin/stdout.
+
+This makes ctx accessible to **any MCP-compatible AI tool** without
+custom hooks or integrations:
+
+- Claude Desktop
+- Cursor
+- Windsurf
+- VS Code Copilot
+- Any tool supporting MCP
+
+### `ctx mcp serve`
+
+Start the MCP server. This command reads JSON-RPC 2.0 requests from
+stdin and writes responses to stdout. It is intended to be launched
+by MCP clients, not run directly.
+
+```
+ctx mcp serve
+```
+
+**Flags:** None. The server uses the configured context directory
+(from `--context-dir`, `CTX_DIR`, `.ctxrc`, or the default `.context`).
+
+---
+
+## Configuration
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "ctx": {
+      "command": "ctx",
+      "args": ["mcp", "serve"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json` in your project:
+
+```json
+{
+  "mcpServers": {
+    "ctx": {
+      "command": "ctx",
+      "args": ["mcp", "serve"]
+    }
+  }
+}
+```
+
+### VS Code (Copilot)
+
+Add to `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "ctx": {
+      "command": "ctx",
+      "args": ["mcp", "serve"]
+    }
+  }
+}
+```
+
+---
+
+## Resources
+
+Resources expose context files as read-only content. Each resource
+has a URI, name, and returns Markdown text.
+
+| URI                          | Name           | Description                                  |
+|------------------------------|----------------|----------------------------------------------|
+| `ctx://context/constitution` | constitution   | Hard rules that must never be violated       |
+| `ctx://context/tasks`        | tasks          | Current work items and their status          |
+| `ctx://context/conventions`  | conventions    | Code patterns and standards                  |
+| `ctx://context/architecture` | architecture   | System architecture documentation            |
+| `ctx://context/decisions`    | decisions      | Architectural decisions with rationale       |
+| `ctx://context/learnings`    | learnings      | Gotchas, tips, and lessons learned           |
+| `ctx://context/glossary`     | glossary       | Project-specific terminology                 |
+| `ctx://context/agent`        | agent          | All files assembled in priority read order   |
+
+The `agent` resource assembles all non-empty context files into a
+single Markdown document, ordered by the configured read priority.
+
+---
+
+## Tools
+
+Tools expose ctx commands as callable operations. Each tool accepts
+JSON arguments and returns text results.
+
+### `ctx_status`
+
+Show context health: file count, token estimate, and per-file summary.
+
+**Arguments:** None.
+
+### `ctx_add`
+
+Add a task, decision, learning, or convention to the context.
+
+| Argument       | Type   | Required | Description                              |
+|----------------|--------|----------|------------------------------------------|
+| `type`         | string | Yes      | Entry type: task, decision, learning, convention |
+| `content`      | string | Yes      | Title or main content                    |
+| `priority`     | string | No       | Priority level (tasks only): high, medium, low |
+| `context`      | string | Conditional | Context field (decisions and learnings) |
+| `rationale`    | string | Conditional | Rationale (decisions only)             |
+| `consequences` | string | Conditional | Consequences (decisions only)          |
+| `lesson`       | string | Conditional | Lesson learned (learnings only)        |
+| `application`  | string | Conditional | How to apply (learnings only)          |
+
+### `ctx_complete`
+
+Mark a task as done by number or text match.
+
+| Argument | Type   | Required | Description                              |
+|----------|--------|----------|------------------------------------------|
+| `query`  | string | Yes      | Task number (e.g. "1") or search text    |
+
+### `ctx_drift`
+
+Detect stale or invalid context. Returns violations, warnings, and
+passed checks.
+
+**Arguments:** None.
+
+---
+
+## Design
+
+The MCP server preserves all six ctx design invariants:
+
+1. **Markdown-on-filesystem** — all state remains in `.context/` files
+2. **Zero runtime dependencies** — no external services required
+3. **Deterministic assembly** — same files produce same output
+4. **Human authority** — tools write to files, humans review
+5. **Local-first** — no network required
+6. **No telemetry** — no data leaves the local machine

internal/bootstrap/bootstrap.go

@@ -22,8 +22,8 @@ import (
 	"github.com/ActiveMemory/ctx/internal/cli/agent"
 	"github.com/ActiveMemory/ctx/internal/cli/changes"
 	"github.com/ActiveMemory/ctx/internal/cli/compact"
-	cliconfig "github.com/ActiveMemory/ctx/internal/cli/config"
 	"github.com/ActiveMemory/ctx/internal/cli/complete"
+	cliconfig "github.com/ActiveMemory/ctx/internal/cli/config"
 	"github.com/ActiveMemory/ctx/internal/cli/decision"
 	"github.com/ActiveMemory/ctx/internal/cli/deps"
 	"github.com/ActiveMemory/ctx/internal/cli/doctor"
@@ -35,11 +35,12 @@ import (
 	"github.com/ActiveMemory/ctx/internal/cli/learnings"
 	"github.com/ActiveMemory/ctx/internal/cli/load"
 	"github.com/ActiveMemory/ctx/internal/cli/loop"
+	climcp "github.com/ActiveMemory/ctx/internal/cli/mcp"
 	"github.com/ActiveMemory/ctx/internal/cli/notify"
 	"github.com/ActiveMemory/ctx/internal/cli/pad"
 	"github.com/ActiveMemory/ctx/internal/cli/pause"
-	"github.com/ActiveMemory/ctx/internal/cli/prompt"
 	"github.com/ActiveMemory/ctx/internal/cli/permissions"
+	"github.com/ActiveMemory/ctx/internal/cli/prompt"
 	"github.com/ActiveMemory/ctx/internal/cli/recall"
 	"github.com/ActiveMemory/ctx/internal/cli/reindex"
 	"github.com/ActiveMemory/ctx/internal/cli/remind"
@@ -88,6 +89,7 @@ func Initialize(cmd *cobra.Command) *cobra.Command {
 		learnings.Cmd,
 		task.Cmd,
 		loop.Cmd,
+		climcp.Cmd,
 		notify.Cmd,
 		pad.Cmd,
 		pause.Cmd,

internal/cli/mcp/mcp.go

@@ -0,0 +1,44 @@
+//   /    ctx:                         https://ctx.ist
+// ,'`./    do you remember?
+// `.,'\
+//   \    Copyright 2026-present Context contributors.
+//                 SPDX-License-Identifier: Apache-2.0
+
+// Package mcp provides the CLI command for running the MCP server.
+package mcp
+
+import (
+	"github.com/spf13/cobra"
+
+	"github.com/ActiveMemory/ctx/internal/config"
+	internalmcp "github.com/ActiveMemory/ctx/internal/mcp"
+	"github.com/ActiveMemory/ctx/internal/rc"
+)
+
+// Cmd returns the mcp command group.
+func Cmd() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "mcp",
+		Short: "Model Context Protocol server",
+		Long:  "Run ctx as an MCP server over stdin/stdout.\n\nThe MCP server exposes context files as resources and ctx commands as tools,\nenabling any MCP-compatible AI tool to access project context.",
+	}
+
+	cmd.AddCommand(serveCmd())
+
+	return cmd
+}
+
+// serveCmd returns the mcp serve subcommand.
+func serveCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:          "serve",
+		Short:        "Start the MCP server (stdin/stdout)",
+		Long:         "Start the MCP server, communicating via JSON-RPC 2.0 over stdin/stdout.\n\nThis command is intended to be invoked by MCP clients (AI tools), not\nrun directly by users. Configure your AI tool to run 'ctx mcp serve'\nas an MCP server.",
+		Annotations:  map[string]string{config.AnnotationSkipInit: "true"},
+		SilenceUsage: true,
+		RunE: func(_ *cobra.Command, _ []string) error {
+			srv := internalmcp.NewServer(rc.ContextDir())
+			return srv.Serve()
+		},
+	}
+}

internal/mcp/doc.go

@@ -0,0 +1,60 @@
+//   /    ctx:                         https://ctx.ist
+// ,'`./    do you remember?
+// `.,'\
+//   \    Copyright 2026-present Context contributors.
+//                 SPDX-License-Identifier: Apache-2.0
+
+// 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
+//
+// # Usage
+//
+//	server := mcp.NewServer(contextDir)
+//	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
+package mcp