opencontext MCP server

---

Most coding agents lose critical decisions between sessions: architecture invariants, API contracts, rejected patterns, and setup quirks. OpenContext solves context loss through a lightweight Model Context Protocol (MCP) server that lets agents read and mutate durable markdown files inside .opencontext/.

No vector databases, no cloud subscriptions, and no hidden state. Memory is plain markdown tracked directly in Git.

---

Quickstart

Run the MCP server directly without installation via npx:

npx -y opencontext-mcp

One-Command Setup

Scaffold OpenContext in the current project interactively:

npx -y opencontext-mcp init

init walks you through the setup (enabling OpenCode and Claude Code integration) and generates everything you need:

• .opencontext/ — directory that holds your context topic files
• .opencontext.json — configuration template
• opencode.json — MCP server entry for OpenCode
• .mcp.json — MCP server entry for Claude Code
• AGENTS.md / CLAUDE.md — workflow reminders for your agents

The init command takes no arguments: it always runs in the current directory, prompts interactively, and never overwrites an existing config.

Client Setup

OpenCode

Add OpenContext to your project MCP configuration (opencode.json) — or let opencontext-mcp init do it for you:

{
  "mcp": {
    "opencontext": {
      "type": "local",
      "command": ["npx", "-y", "opencontext-mcp"],
      "enabled": true
    }
  }
}

Cursor / Claude Desktop / Windsurf

Add OpenContext to your MCP settings file (claude_desktop_config.json or Cursor MCP settings):

{
  "mcpServers": {
    "opencontext": {
      "command": "npx",
      "args": ["-y", "opencontext-mcp"]
    }
  }
}

---

Remote Access (HTTP)

Expose the MCP server over the network with the Streamable HTTP transport. The endpoint URL is printed to stderr on startup.

# Plain HTTP on 127.0.0.1:3032 (default)
opencontext-mcp --http

# Custom port / bind to all interfaces
opencontext-mcp server --http --port 8787 --host 0.0.0.0

The server listens at http://<host>:<port>/mcp (stateless Streamable HTTP — one request at a time, no sessions). GET / returns basic server info, handy for a browser health check.

---

Core Tools

Tool	Parameters	Description
read_context	topic? (optional string)	Reads a specific context topic, or returns the lightweight topic index (~100 tokens) if omitted.
save_context	topic (string), content (string)	Writes or mutates markdown memory inside .opencontext/<topic>.md with built-in write guards and symlink protections.
delete_context	topic (string)	Removes an obsolete topic file and automatically rebuilds the topic index.

---

ADR Lifecycle & Frontmatter

Topics support optional YAML frontmatter to track lifecycle status — useful when architectural decisions evolve and old context should be visible but clearly flagged as outdated.

---
description: OAuth2 + PKCE authentication flow
status: active
supersedes: auth_v1
---

# Authentication v2

Migrated from JWT to OAuth2 with PKCE.

Supported frontmatter keys:

Key	Values	Description
description	string	Short summary used in the auto-generated index.
status	active | deprecated | superseded	Lifecycle status. Defaults to active when omitted.
supersedes	string	Topic name this topic replaces (set on the newer topic).
superseded_by	string	Topic name that replaced this one (set on the older topic).

Non-active topics automatically receive [DEPRECATED] or [SUPERSEDED] badges in the auto-generated index.md, along with cross-references showing which topic replaced or was replaced.

---

Agent Workflows

Instruct your agents to automatically leverage project context. Add this snippet to your .cursorrules, CLAUDE.md, or system prompt:

Before making structural code changes, run `read_context` to inspect existing project topics and architectural decisions.

Whenever a new architectural convention, database schema, or API rule is established or refactored, call `save_context` with a concise, topic-scoped markdown summary. Use YAML frontmatter (status, supersedes) when updating conventions to track lifecycle changes.

When a topic becomes obsolete, call `delete_context` to remove it. For deprecated topics that should remain visible, set status: deprecated or status: superseded in the frontmatter instead of deleting.

---

Configuration

Customize storage paths and security boundaries with an optional .opencontext.json file in your repository root (plain JSON — comments are not supported):

{
  "path": ".opencontext",
  "readOnly": false,
  "autoIndex": true,
  "guard": {
    "enabled": true,
    "maxFileSizeKb": 50,
    "strictPatternCheck": true
  }
}

---

Local Development

# Clone and install dependencies
git clone [https://github.com/slxca/opencontext.git](https://github.com/slxca/opencontext.git)
cd opencontext
pnpm install

# Build & run tests
pnpm build
pnpm test

---

Documentation

For advanced setup guides, guard parameters, and agent prompt templates, visit opencntx.dev/docs.

Contributing

Contributions are welcome. Please ensure all unit tests and typechecks pass before submitting a pull request:

pnpm typecheck && pnpm test