opencontext-mcp 1.0.0 → 1.2.0

package/README.md

@@ -1,47 +1,39 @@
-# OpenContext MCP
+<p align="center">
+  <a href="https://opencntx.dev">
+    <img src="https://github.com/slxca/opencontext/blob/master/apps/web/public/opencontext.png?raw=true" alt="OpenContext logo" width="500">
+  </a>
+</p>
 
-[![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/)
-[![Website](https://img.shields.io/badge/URL-opencntx.dev-c42f52?link=https%3A%2F%2Fopencntx.dev)](https://opencntx.dev/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+<p align="center"><b>Persistent, project-local memory for AI coding agents.</b></p>
 
-OpenContext MCP gives AI agents persistent, project-local memory.
+<p align="center">
+  <a href="https://opencntx.dev"><img alt="Website" src="https://img.shields.io/badge/website-opencntx.dev-191919?style=flat-square" /></a>
+  <a href="https://www.npmjs.com/package/opencontext-mcp"><img alt="npm version" src="https://img.shields.io/npm/v/opencontext-mcp?style=flat-square" /></a>
+  <a href="https://github.com/slxca/opencontext/actions"><img alt="CI status" src="https://img.shields.io/github/actions/workflow/status/slxca/opencontext/ci.yml?style=flat-square&branch=master" /></a>
+</p>
 
-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.
+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/`.
 
-## Features
+No vector databases, no cloud subscriptions, and no hidden state. Memory is plain markdown tracked directly in Git.
 
-- `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
+### Quickstart
 
-You normally do not need to install OpenContext MCP manually. Configure your MCP client to run it with `npx`:
+Run directly without installation via `npx`:
 
 ```bash
 npx -y opencontext-mcp
-```
-
-For local development in this repository:
 
-```bash
-pnpm install
-pnpm build
-pnpm start
 ```
 
-## MCP Client Setup
+### Client Setup
 
-### OpenCode
+#### OpenCode
 
-Add OpenContext MCP to your OpenCode MCP configuration:
+Add OpenContext to your project MCP configuration (`opencode.json`):
 
 ```json
 {
@@ -53,11 +45,12 @@ Add OpenContext MCP to your OpenCode MCP configuration:
     }
   }
 }
+
 ```
 
-### Cursor / Claude Desktop
+#### Cursor / Claude Desktop / Windsurf
 
-Cursor and Claude Desktop use the same MCP server configuration:
+Add OpenContext to your MCP settings file (`claude_desktop_config.json` or Cursor MCP settings):
 
 ```json
 {
@@ -68,128 +61,116 @@ Cursor and Claude Desktop use the same MCP server configuration:
     }
   }
 }
+
 ```
 
-Restart your MCP client after updating the configuration.
+---
 
-## How It Works
+### Core Tools
 
-OpenContext MCP stores files relative to the process working directory used by your MCP client:
+| 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. |
 
-```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`.
+### ADR Lifecycle & Frontmatter
 
-## Available Tools
+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.
 
-### `save_context`
+````markdown
+---
+description: OAuth2 + PKCE authentication flow
+status: active
+supersedes: auth_v1
+---
 
-Saves markdown content to `.opencontext/<topic>.md`. Existing files are overwritten.
+# Authentication v2
 
-Arguments:
+Migrated from JWT to OAuth2 with PKCE.
+````
 
-| Name      | Type   | Required | Description                                   |
-| --------- | ------ | -------- | --------------------------------------------- |
-| `topic`   | string | yes      | Lowercase snake_case or kebab-case topic name |
-| `content` | string | yes      | Markdown content to save                      |
+**Supported frontmatter keys:**
 
-Example use:
+| 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)*. |
 
-```text
-Save our API conventions under topic api-contracts.
-```
+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.
 
-### `read_context`
+---
 
-Reads one saved topic, or lists all topics when no topic is provided.
+### Agent Workflows
 
-Arguments:
+Instruct your agents to automatically leverage project context. Add this snippet to your `.cursorrules`, `CLAUDE.md`, or system prompt:
 
-| Name    | Type   | Required | Description   |
-| ------- | ------ | -------- | ------------- |
-| `topic` | string | no       | Topic to read |
+```markdown
+Before making structural code changes, run `read_context` to inspect existing project topics and architectural decisions.
 
-Example use:
+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.
 
-```text
-Read the architecture context before changing the routing layer.
+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.
 ```
 
-## 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.
+### Configuration
 
-Use save_context whenever you learn a durable project rule, architectural decision, convention, API contract, or debugging note that future agents should know.
+Customize storage paths and security boundaries with an optional `.opencontext.jsonc` file in your repository root:
 
-Prefer small, focused context topics in snake_case or kebab-case. Keep the content concise, factual, and written in markdown.
-```
+```jsonc
+{
+  // Storage location (default: ".opencontext")
+  "path": ".opencontext",
 
-Recommended workflow:
+  // Prevent agents from writing or updating files
+  "readOnly": false,
 
-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.
+  // Auto-generate index.md with topic descriptions
+  "autoIndex": true,
 
-Copy-ready agent prompts:
+  // Write guard & prompt injection defenses
+  "guard": {
+    "enabled": true,
+    "maxFileSizeKb": 50,
+    "strictPatternCheck": true
+  }
+}
 
-- [`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:
+### Local Development
 
 ```bash
-git add .opencontext
-```
+# Clone and install dependencies
+git clone [https://github.com/slxca/opencontext.git](https://github.com/slxca/opencontext.git)
+cd opencontext
+pnpm install
 
-Or ignore it when context should stay local:
+# Build & run tests
+pnpm build
+pnpm test
 
-```gitignore
-.opencontext/
 ```
 
-Because files are plain markdown, both approaches are safe and easy to audit.
+---
 
-## Development
+### Documentation
 
-```bash
-pnpm install
-pnpm build        # compile TypeScript
-pnpm typecheck    # type-check without emitting
-pnpm test         # run vitest suite
-pnpm start        # start the MCP server
-```
+For advanced setup guides, guard parameters, and agent prompt templates, visit **[opencntx.dev/docs](https://www.google.com/search?q=https://opencntx.dev/docs)**.
 
-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
-```
+### Contributing
 
-## License
+Contributions are welcome. Please ensure all unit tests and typechecks pass before submitting a pull request:
 
-MIT
+```bash
+pnpm typecheck && pnpm test
+
+```

package/dist/config.d.ts

@@ -0,0 +1,24 @@
+export interface OpenContextConfig {
+    $schema?: string;
+    path?: string;
+    readOnly?: boolean;
+    disabled?: boolean;
+    autoIndex?: boolean;
+    history?: {
+        enabled?: boolean;
+        maxBackupsPerTopic?: number;
+        retentionDays?: number;
+    };
+    guard?: {
+        enabled?: boolean;
+        maxFileSizeKb?: number;
+        strictPatternCheck?: boolean;
+    };
+}
+export type ResolvedConfig = Required<Omit<OpenContextConfig, "$schema">>;
+export declare const DEFAULT_CONFIG: ResolvedConfig;
+/**
+ * Loads configuration from .opencontext.jsonc or .opencontext.json in the given directory.
+ * Falls back to DEFAULT_CONFIG if no file exists or parsing fails.
+ */
+export declare function loadConfig(cwd?: string): Promise<ResolvedConfig>;

package/dist/config.js

@@ -0,0 +1,145 @@
+import { readFile } from "node:fs/promises";
+import * as path from "node:path";
+export const DEFAULT_CONFIG = {
+    path: ".opencontext",
+    readOnly: false,
+    disabled: false,
+    autoIndex: true,
+    history: {
+        enabled: false,
+        maxBackupsPerTopic: 5,
+        retentionDays: 7,
+    },
+    guard: {
+        enabled: true,
+        maxFileSizeKb: 50,
+        strictPatternCheck: true,
+    },
+};
+const CONFIG_CANDIDATES = [".opencontext.jsonc", ".opencontext.json"];
+/**
+ * Strips JSONC content into parseable JSON by removing comments and trailing commas.
+ * Handles single-line (//), multi-line (/* * /), and trailing commas.
+ * Trailing comma removal is token-aware to avoid modifying string literals.
+ */
+function stripJsonComments(raw) {
+    let result = "";
+    let i = 0;
+    const len = raw.length;
+    while (i < len) {
+        const ch = raw[i];
+        // Strings: copy verbatim (including escaped characters)
+        if (ch === '"') {
+            result += ch;
+            i++;
+            while (i < len && raw[i] !== '"') {
+                if (raw[i] === "\\") {
+                    result += raw[i];
+                    i++;
+                }
+                if (i < len) {
+                    result += raw[i];
+                    i++;
+                }
+            }
+            if (i < len) {
+                result += raw[i]; // closing quote
+                i++;
+            }
+            continue;
+        }
+        // Single-line comment: skip until newline
+        if (ch === "/" && i + 1 < len && raw[i + 1] === "/") {
+            while (i < len && raw[i] !== "\n") {
+                i++;
+            }
+            continue;
+        }
+        // Multi-line comment: skip until */
+        if (ch === "/" && i + 1 < len && raw[i + 1] === "*") {
+            i += 2;
+            while (i < len - 1 && !(raw[i] === "*" && raw[i + 1] === "/")) {
+                i++;
+            }
+            i += 2; // skip */
+            continue;
+        }
+        // Trailing comma: skip comma if followed by optional whitespace/comments then } or ]
+        if (ch === ",") {
+            let j = i + 1;
+            // Skip whitespace and comments to find the next meaningful token
+            while (j < len) {
+                if (raw[j] === " " || raw[j] === "\t" || raw[j] === "\n" || raw[j] === "\r") {
+                    j++;
+                }
+                else if (raw[j] === "/" && j + 1 < len && raw[j + 1] === "/") {
+                    while (j < len && raw[j] !== "\n")
+                        j++;
+                }
+                else if (raw[j] === "/" && j + 1 < len && raw[j + 1] === "*") {
+                    j += 2;
+                    while (j < len - 1 && !(raw[j] === "*" && raw[j + 1] === "/"))
+                        j++;
+                    j += 2;
+                }
+                else {
+                    break;
+                }
+            }
+            if (j < len && (raw[j] === "}" || raw[j] === "]")) {
+                i = j; // skip comma and whitespace/comments, continue from closing bracket
+                continue;
+            }
+            // Not a trailing comma — keep it
+            result += ch;
+            i++;
+            continue;
+        }
+        result += ch;
+        i++;
+    }
+    return result;
+}
+function deepMerge(target, source) {
+    const result = { ...target };
+    for (const key of Object.keys(source)) {
+        const sourceVal = source[key];
+        const targetVal = result[key];
+        if (sourceVal !== null &&
+            typeof sourceVal === "object" &&
+            !Array.isArray(sourceVal) &&
+            targetVal !== null &&
+            typeof targetVal === "object" &&
+            !Array.isArray(targetVal)) {
+            result[key] = deepMerge(targetVal, sourceVal);
+        }
+        else if (sourceVal !== undefined) {
+            result[key] = sourceVal;
+        }
+    }
+    return result;
+}
+/**
+ * Loads configuration from .opencontext.jsonc or .opencontext.json in the given directory.
+ * Falls back to DEFAULT_CONFIG if no file exists or parsing fails.
+ */
+export async function loadConfig(cwd = process.cwd()) {
+    for (const filename of CONFIG_CANDIDATES) {
+        const filePath = path.join(cwd, filename);
+        try {
+            const raw = await readFile(filePath, "utf8");
+            const cleaned = stripJsonComments(raw);
+            const parsed = JSON.parse(cleaned);
+            return deepMerge(DEFAULT_CONFIG, parsed);
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                continue; // file doesn't exist, try next candidate
+            }
+            console.error(`OpenContext: failed to parse ${filename}: ${error.message}`);
+            return DEFAULT_CONFIG;
+        }
+    }
+    return DEFAULT_CONFIG;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

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

package/dist/context-store.d.ts

@@ -1,9 +1,63 @@
+import { type ResolvedConfig } from "./config.js";
+/**
+ * Manages context file storage operations.
+ * Handles reading, writing, and listing context files in the configured directory.
+ */
 export declare class ContextStore {
     private readonly basePath;
-    constructor(basePath?: string);
+    private readonly config;
+    private readonly contextDir;
+    constructor(basePath?: string, config?: ResolvedConfig);
+    /** Returns the absolute path to the context directory. */
     getContextDirectory(): string;
+    /** Returns the absolute path to a topic file. */
     getTopicFilePath(topic: string): string;
+    /**
+     * Saves context content to a topic file.
+     * Validates payload using WriteGuard before writing.
+     * @param topicInput - Topic name (will be validated and trimmed)
+     * @param content - Markdown content to save
+     * @returns Success message with file location
+     * @throws UserInputError if validation fails
+     */
     saveContext(topicInput: string, content: string): Promise<string>;
+    /**
+     * Reads context content from a topic file, or lists all topics if none specified.
+     * @param topicInput - Optional topic name to read
+     * @returns Topic content or list of available topics
+     * @throws UserInputError if topic doesn't exist or is invalid
+     */
     readContext(topicInput?: string): Promise<string>;
+    /**
+     * Deletes a context topic file from the context directory.
+     * @param topicInput - Topic name to delete
+     * @returns Success message with confirmation
+     * @throws UserInputError if topic doesn't exist or is invalid
+     */
+    deleteContext(topicInput: string): Promise<string>;
+    /**
+     * Lists all available context topics.
+     * Scans the context directory for .md files and returns sorted topic names.
+     * @returns Sorted array of topic names
+     */
     listTopics(): Promise<string[]>;
+    /**
+     * Parses YAML frontmatter from markdown content.
+     * Returns extracted fields or empty object if no frontmatter found.
+     * Uses simple line-by-line parsing — no external YAML dependency.
+     */
+    private parseFrontmatter;
+    /**
+     * Extracts a short description from markdown content.
+     * Strategy: frontmatter description → first heading → first paragraph → fallback.
+     * @param content - Raw markdown content
+     * @returns Truncated description (max 120 chars)
+     */
+    private extractDescription;
+    /**
+     * Rebuilds the auto-generated index.md file in the context directory.
+     * Scans all topic files, extracts metadata, and writes a compact index.
+     * @returns The generated index markdown content
+     */
+    rebuildContextIndex(): Promise<string>;
 }