opencontext-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenContext Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,209 @@
+# OpenContext MCP
+
+[![MCP](https://img.shields.io/badge/MCP-compatible-2563eb)](https://modelcontextprotocol.io/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6)](https://www.typescriptlang.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-20%2B-339933)](https://nodejs.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+OpenContext MCP gives AI agents persistent, project-local memory.
+
+Most coding agents lose important decisions between sessions: architecture rules, naming conventions, API contracts, migration notes, and hard-won debugging context. OpenContext MCP solves that by exposing a tiny Model Context Protocol server that lets agents save and read markdown files in a local `.opencontext/` directory inside each project.
+
+The result is simple and transparent: your agent gets memory, and you keep full control because the memory is plain markdown committed or ignored however you choose.
+
+## Features
+
+- `save_context`: save markdown context to `.opencontext/<topic>.md`
+- `read_context`: read one saved topic or list all available topics
+- Project-specific storage based on the client's current working directory
+- No database, account, cloud sync, or hidden state
+- Works with MCP-compatible clients over stdio
+- Built with strict TypeScript and the official `@modelcontextprotocol/sdk`
+
+## Installation
+
+You normally do not need to install OpenContext MCP manually. Configure your MCP client to run it with `npx`:
+
+```bash
+npx -y opencontext-mcp
+```
+
+For local development in this repository:
+
+```bash
+pnpm install
+pnpm build
+pnpm start
+```
+
+## MCP Client Setup
+
+### OpenCode
+
+Add OpenContext MCP to your OpenCode MCP configuration:
+
+```json
+{
+  "mcp": {
+    "opencontext": {
+      "type": "local",
+      "command": ["npx", "-y", "opencontext-mcp"],
+      "enabled": true
+    }
+  }
+}
+```
+
+### Cursor
+
+Add this server to your Cursor MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "opencontext": {
+      "command": "npx",
+      "args": ["-y", "opencontext-mcp"]
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Add this entry to your Claude Desktop MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "opencontext": {
+      "command": "npx",
+      "args": ["-y", "opencontext-mcp"]
+    }
+  }
+}
+```
+
+Restart your MCP client after updating configuration.
+
+## How It Works
+
+OpenContext MCP stores files relative to the process working directory used by your MCP client:
+
+```text
+your-project/
+  .opencontext/
+    architecture.md
+    api-contracts.md
+    coding_rules.md
+```
+
+Topics must be lowercase snake_case or kebab-case, such as `architecture`, `api-contracts`, or `coding_rules`.
+
+## Available Tools
+
+### `save_context`
+
+Saves markdown content to `.opencontext/<topic>.md`. Existing files are overwritten.
+
+Arguments:
+
+| Name      | Type   | Required | Description                                   |
+| --------- | ------ | -------- | --------------------------------------------- |
+| `topic`   | string | yes      | Lowercase snake_case or kebab-case topic name |
+| `content` | string | yes      | Markdown content to save                      |
+
+Example use:
+
+```text
+Save our API conventions under topic api-contracts.
+```
+
+### `read_context`
+
+Reads one saved topic, or lists all topics when no topic is provided.
+
+Arguments:
+
+| Name    | Type   | Required | Description   |
+| ------- | ------ | -------- | ------------- |
+| `topic` | string | no       | Topic to read |
+
+Example use:
+
+```text
+Read the architecture context before changing the routing layer.
+```
+
+## How To Instruct Agents
+
+MCP tools are most useful when your agent is explicitly told when to use them. Add instructions like these to your system prompt or project rules:
+
+```text
+Always use read_context before making code changes. First list available topics, then read any topic relevant to the task.
+
+Use save_context whenever you learn a durable project rule, architectural decision, convention, API contract, or debugging note that future agents should know.
+
+Prefer small, focused context topics in snake_case or kebab-case. Keep the content concise, factual, and written in markdown.
+```
+
+Recommended workflow:
+
+1. Ask an architect or planning agent to analyze the project and save durable decisions with `save_context`.
+2. Ask build agents to call `read_context` before coding.
+3. Let agents update context when they discover something that should survive the current chat.
+4. Review `.opencontext/` files like normal project documentation.
+
+Copy-ready agent prompts:
+
+- [`examples/plan-agent.md`](examples/plan-agent.md) -- architect that analyzes requirements and saves context
+- [`examples/build-agent.md`](examples/build-agent.md) -- developer that reads context before coding
+
+## Version Control
+
+You can commit `.opencontext/` when it contains team-wide knowledge:
+
+```bash
+git add .opencontext
+```
+
+Or ignore it when context should stay local:
+
+```gitignore
+.opencontext/
+```
+
+Because files are plain markdown, both approaches are safe and easy to audit.
+
+## Development
+
+```bash
+pnpm install
+pnpm build        # compile TypeScript
+pnpm typecheck    # type-check without emitting
+pnpm test         # run vitest suite
+pnpm start        # start the MCP server
+```
+
+Project structure:
+
+```text
+src/
+  index.ts            CLI entrypoint (stdio transport, startup error handling)
+  server.ts           McpServer factory and tool registration
+  context-store.ts    Filesystem operations for .opencontext/
+  validation.ts       Topic validation and input rules
+  types.ts            Shared constants, error classes, and result helpers
+test/
+  validation.test.ts  Unit tests for topic validation
+  context-store.test.ts  Unit tests for read/write/list operations
+examples/
+  plan-agent.md       Architect system prompt
+  build-agent.md      Developer system prompt
+README.md             User documentation
+LICENSE               MIT license
+```
+
+## License
+
+MIT

package/dist/context-store.d.ts

@@ -0,0 +1,9 @@
+export declare class ContextStore {
+    private readonly basePath;
+    constructor(basePath?: string);
+    getContextDirectory(): string;
+    getTopicFilePath(topic: string): string;
+    saveContext(topicInput: string, content: string): Promise<string>;
+    readContext(topicInput?: string): Promise<string>;
+    listTopics(): Promise<string[]>;
+}

package/dist/context-store.js

@@ -0,0 +1,59 @@
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { CONTEXT_DIRECTORY_NAME, UserInputError, isNodeError } from "./types.js";
+import { validateTopic } from "./validation.js";
+export class ContextStore {
+    basePath;
+    constructor(basePath = process.cwd()) {
+        this.basePath = basePath;
+    }
+    getContextDirectory() {
+        return path.join(this.basePath, CONTEXT_DIRECTORY_NAME);
+    }
+    getTopicFilePath(topic) {
+        return path.join(this.getContextDirectory(), `${topic}.md`);
+    }
+    async saveContext(topicInput, content) {
+        const topic = validateTopic(topicInput);
+        const contextDirectory = this.getContextDirectory();
+        const filePath = this.getTopicFilePath(topic);
+        await mkdir(contextDirectory, { recursive: true });
+        await writeFile(filePath, content, "utf8");
+        return `Saved context topic "${topic}" to ${CONTEXT_DIRECTORY_NAME}/${topic}.md.`;
+    }
+    async readContext(topicInput) {
+        if (topicInput !== undefined) {
+            const topic = validateTopic(topicInput);
+            try {
+                return await readFile(this.getTopicFilePath(topic), "utf8");
+            }
+            catch (error) {
+                if (isNodeError(error) && error.code === "ENOENT") {
+                    throw new UserInputError(`No context found for topic "${topic}" at ${CONTEXT_DIRECTORY_NAME}/${topic}.md.`);
+                }
+                throw error;
+            }
+        }
+        const topics = await this.listTopics();
+        if (topics.length === 0) {
+            return `No OpenContext topics found in ${CONTEXT_DIRECTORY_NAME}/. Use save_context to create one.`;
+        }
+        return `Available OpenContext topics:\n\n${topics.map((topic) => `- ${topic}`).join("\n")}`;
+    }
+    async listTopics() {
+        try {
+            const entries = await readdir(this.getContextDirectory(), { withFileTypes: true });
+            return entries
+                .filter((entry) => entry.isFile() && entry.name.endsWith(".md"))
+                .map((entry) => entry.name.slice(0, -".md".length))
+                .sort((a, b) => a.localeCompare(b));
+        }
+        catch (error) {
+            if (isNodeError(error) && error.code === "ENOENT") {
+                return [];
+            }
+            throw error;
+        }
+    }
+}
+//# sourceMappingURL=context-store.js.map

package/dist/context-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-store.js","sourceRoot":"","sources":["../src/context-store.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createOpenContextServer } from "./server.js";
+import { SERVER_NAME, getErrorMessage } from "./types.js";
+async function main() {
+    const server = createOpenContextServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((error) => {
+    console.error(`Failed to start ${SERVER_NAME}: ${getErrorMessage(error)}`);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE1D,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,uBAAuB,EAAE,CAAC;IACzC,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IAC9B,OAAO,CAAC,KAAK,CAAC,mBAAmB,WAAW,KAAK,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAC3E,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function createOpenContextServer(basePath?: string): McpServer;

package/dist/server.js

@@ -0,0 +1,51 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { ContextStore } from "./context-store.js";
+import { SERVER_NAME, SERVER_VERSION, getErrorMessage, textResult } from "./types.js";
+export function createOpenContextServer(basePath) {
+    const store = new ContextStore(basePath);
+    const server = new McpServer({
+        name: SERVER_NAME,
+        version: SERVER_VERSION,
+    });
+    server.registerTool("save_context", {
+        title: "Save Context",
+        description: "Persist markdown project context, architectural rules, or decisions into .opencontext/<topic>.md in the current working directory.",
+        inputSchema: {
+            topic: z
+                .string()
+                .min(1)
+                .describe("Context topic name in snake_case or kebab-case, for example api_contracts or auth-rules."),
+            content: z.string().min(1).describe("Markdown content to save for this project topic."),
+        },
+    }, async ({ topic, content }) => {
+        try {
+            const result = await store.saveContext(topic, content);
+            return textResult(result);
+        }
+        catch (error) {
+            return textResult(`OpenContext error: ${getErrorMessage(error)}`, true);
+        }
+    });
+    server.registerTool("read_context", {
+        title: "Read Context",
+        description: "Read a saved OpenContext topic, or list all available topics when no topic is provided.",
+        inputSchema: {
+            topic: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Optional topic name in snake_case or kebab-case. Omit to list all saved topics."),
+        },
+    }, async ({ topic }) => {
+        try {
+            const result = await store.readContext(topic);
+            return textResult(result);
+        }
+        catch (error) {
+            return textResult(`OpenContext error: ${getErrorMessage(error)}`, true);
+        }
+    });
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEtF,MAAM,UAAU,uBAAuB,CAAC,QAAiB;IACvD,MAAM,KAAK,GAAG,IAAI,YAAY,CAAC,QAAQ,CAAC,CAAC;IAEzC,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE,cAAc;KACxB,CAAC,CAAC;IAEH,MAAM,CAAC,YAAY,CACjB,cAAc,EACd;QACE,KAAK,EAAE,cAAc;QACrB,WAAW,EACT,oIAAoI;QACtI,WAAW,EAAE;YACX,KAAK,EAAE,CAAC;iBACL,MAAM,EAAE;iBACR,GAAG,CAAC,CAAC,CAAC;iBACN,QAAQ,CACP,0FAA0F,CAC3F;YACH,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,kDAAkD,CAAC;SACxF;KACF,EACD,KAAK,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE;QAC3B,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,WAAW,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;YACvD,OAAO,UAAU,CAAC,MAAM,CAAC,CAAC;QAC5B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,UAAU,CAAC,sBAAsB,eAAe,CAAC,KAAK,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;QAC1E,CAAC;IACH,CAAC,CACF,CAAC;IAEF,MAAM,CAAC,YAAY,CACjB,cAAc,EACd;QACE,KAAK,EAAE,cAAc;QACrB,WAAW,EACT,yFAAyF;QAC3F,WAAW,EAAE;YACX,KAAK,EAAE,CAAC;iBACL,MAAM,EAAE;iBACR,GAAG,CAAC,CAAC,CAAC;iBACN,QAAQ,EAAE;iBACV,QAAQ,CACP,iFAAiF,CAClF;SACJ;KACF,EACD,KAAK,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE;QAClB,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;YAC9C,OAAO,UAAU,CAAC,MAAM,CAAC,CAAC;QAC5B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,UAAU,CAAC,sBAAsB,eAAe,CAAC,KAAK,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;QAC1E,CAAC;IACH,CAAC,CACF,CAAC;IAEF,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,16 @@
+export declare const SERVER_NAME = "opencontext-mcp";
+export declare const SERVER_VERSION = "0.1.0";
+export declare const CONTEXT_DIRECTORY_NAME = ".opencontext";
+export declare const TOPIC_PATTERN: RegExp;
+export declare class UserInputError extends Error {
+    constructor(message: string);
+}
+export declare function textResult(text: string, isError?: boolean): {
+    isError?: boolean;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+export declare function getErrorMessage(error: unknown): string;
+export declare function isNodeError(error: unknown): error is NodeJS.ErrnoException;

package/dist/types.js

@@ -0,0 +1,31 @@
+export const SERVER_NAME = "opencontext-mcp";
+export const SERVER_VERSION = "0.1.0";
+export const CONTEXT_DIRECTORY_NAME = ".opencontext";
+export const TOPIC_PATTERN = /^[a-z0-9]+(?:[_-][a-z0-9]+)*$/;
+export class UserInputError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "UserInputError";
+    }
+}
+export function textResult(text, isError = false) {
+    return {
+        content: [
+            {
+                type: "text",
+                text,
+            },
+        ],
+        ...(isError ? { isError: true } : {}),
+    };
+}
+export function getErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return "An unknown error occurred.";
+}
+export function isNodeError(error) {
+    return error instanceof Error && "code" in error;
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,WAAW,GAAG,iBAAiB,CAAC;AAC7C,MAAM,CAAC,MAAM,cAAc,GAAG,OAAO,CAAC;AACtC,MAAM,CAAC,MAAM,sBAAsB,GAAG,cAAc,CAAC;AACrD,MAAM,CAAC,MAAM,aAAa,GAAG,+BAA+B,CAAC;AAE7D,MAAM,OAAO,cAAe,SAAQ,KAAK;IACvC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AAED,MAAM,UAAU,UAAU,CAAC,IAAY,EAAE,OAAO,GAAG,KAAK;IACtD,OAAO;QACL,OAAO,EAAE;YACP;gBACE,IAAI,EAAE,MAAe;gBACrB,IAAI;aACL;SACF;QACD,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACtC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,OAAO,KAAK,CAAC,OAAO,CAAC;IACvB,CAAC;IAED,OAAO,4BAA4B,CAAC;AACtC,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,OAAO,KAAK,YAAY,KAAK,IAAI,MAAM,IAAI,KAAK,CAAC;AACnD,CAAC"}

package/dist/validation.d.ts

@@ -0,0 +1 @@
+export declare function validateTopic(topicInput: string): string;

package/dist/validation.js

@@ -0,0 +1,9 @@
+import { TOPIC_PATTERN, UserInputError } from "./types.js";
+export function validateTopic(topicInput) {
+    const topic = topicInput.trim();
+    if (!TOPIC_PATTERN.test(topic)) {
+        throw new UserInputError("Topic must be snake_case or kebab-case using lowercase letters, numbers, underscores, or hyphens.");
+    }
+    return topic;
+}
+//# sourceMappingURL=validation.js.map

package/dist/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE3D,MAAM,UAAU,aAAa,CAAC,UAAkB;IAC9C,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,EAAE,CAAC;IAEhC,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,cAAc,CACtB,mGAAmG,CACpG,CAAC;IACJ,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}

package/examples/build-agent.md

@@ -0,0 +1,48 @@
+# OpenContext Build Agent
+
+Copy this prompt into your AI client's system prompt to turn it into a developer that follows rules saved by the Plan Agent.
+
+## System Prompt
+
+You are the OpenContext Build Agent: a pragmatic senior developer responsible for implementing changes while strictly following project context saved by the Plan Agent.
+
+Before writing or editing any code, you must use the `read_context` tool with no topic to list available OpenContext topics. Then read all topics relevant to the requested work. If relevant context exists, follow it. If the user's request conflicts with saved context, stop and ask for clarification before changing code.
+
+Your responsibilities:
+
+- Read OpenContext before coding.
+- Inspect the codebase and make the smallest correct change.
+- Preserve existing architecture, naming conventions, and testing strategy.
+- Run appropriate verification commands when feasible.
+- Use `save_context` when you discover a durable rule, convention, decision, or debugging note future agents should know.
+- Do not overwrite saved context with speculative or temporary information.
+
+Required workflow:
+
+```text
+1. Call read_context with no topic.
+2. Read each relevant topic with read_context.
+3. Inspect the affected code.
+4. Implement the smallest correct change.
+5. Run relevant tests, type checks, or builds.
+6. Save any newly discovered durable context with save_context.
+7. Summarize what changed and what was verified.
+```
+
+If no OpenContext topics exist, state that no saved context was available, then proceed by inspecting the repository directly.
+
+Build output format:
+
+```text
+Changed
+<files or behavior changed>
+
+Context Used
+<topics read or note that no context existed>
+
+Verification
+<commands run and results>
+
+Context Saved
+<topics saved or updated, if any>
+```

package/examples/plan-agent.md

@@ -0,0 +1,53 @@
+# OpenContext Plan Agent
+
+Copy this prompt into your AI client's system prompt to turn it into an architect that uses OpenContext MCP.
+
+## System Prompt
+
+You are the OpenContext Plan Agent: a senior software architect responsible for turning requirements into clear implementation plans and durable project context.
+
+Before planning, use the `read_context` tool with no topic to list available OpenContext topics. Read every topic relevant to the user's request before making recommendations. If no context exists, inspect the repository and infer only what is supported by evidence in the codebase.
+
+Your responsibilities:
+
+- Analyze the user's requirement and the current codebase before proposing changes.
+- Identify architectural constraints, project conventions, API contracts, data model decisions, and implementation risks.
+- Create a practical step-by-step plan that a build agent can execute.
+- Use `save_context` to persist durable decisions, rules, and conventions that future agents should follow.
+- Prefer concise markdown context organized under focused snake_case or kebab-case topics.
+
+When using `save_context`, choose topics such as:
+
+- `architecture`
+- `coding_rules`
+- `api-contracts`
+- `data-model`
+- `testing-strategy`
+
+Context you save must be factual and durable. Do not save temporary guesses, chat-only preferences, or unresolved options unless they are clearly marked as open questions.
+
+Plan output format:
+
+```text
+Summary
+<one-paragraph explanation of the intended solution>
+
+Relevant Context Read
+<topics read and what mattered>
+
+Architecture Decisions
+<decisions made or confirmed>
+
+Implementation Plan
+1. <step>
+2. <step>
+3. <step>
+
+Risks And Checks
+<known risks, tests, and verification steps>
+
+Context Saved
+<topics saved or updated>
+```
+
+Always save newly discovered durable context before finishing your response.

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "opencontext-mcp",
+  "version": "0.1.0",
+  "description": "A Model Context Protocol server for persistent project-specific AI agent context.",
+  "type": "module",
+  "bin": {
+    "opencontext-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "examples"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "start": "node dist/index.js",
+    "prepublishOnly": "pnpm build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "agents",
+    "context",
+    "memory"
+  ],
+  "repository": {
+    "url": "git+https://github.com/slxca/opencontext.git"
+  },
+  "bugs": {
+    "url": "https://github.com/slxca/mockr.js/issues",
+    "email": "bugs@s-luca.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "slxca <hello@slxca.com> (https://slxca.com)",
+  "funding": "https://github.com/sponsors/slxca",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "packageManager": "pnpm@9.15.4",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.17.4",
+    "zod": "^4.5.4"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.1",
+    "typescript": "^5.7.3",
+    "vitest": "^4.1.11"
+  }
+}