convez.ai
MCP Server
vibhasdutta

context-mcp

vibhasdutta/context-mcp

Ver no GitHub
InicialPluginScore · de 0 a 100

Persistent memory and codebase knowledge graph for AI coding assistants — delivered as a single MCP server.

Instalação

$npx convez-ai vibhasdutta/context-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 3 meses
Versão
v1.1.3
Issues abertas
0
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

Persistent memory and codebase knowledge graph for AI coding assistants — delivered as a single MCP server.

One shared context store across Claude Code, Cursor, Gemini CLI, Codex, Windsurf, VS Code Copilot, Claude.ai, and ChatGPT. Save context from one AI, pick it up in another.


The Problem

Every conversation with an AI assistant starts from zero. The AI re-reads files it already read yesterday, re-discovers architecture it already understood, re-derives decisions that were already made. You repeat context. You paste the same background.

This gets worse as projects grow — reading 20 files to answer "what calls this function?" burns thousands of tokens every time.


What It Solves

  • Persistent memory — decisions, bugs, notes, and config saved across sessions, loaded automatically at conversation start
  • Shared store — ~/.context-mcp/projects/<name>/ per-project on your machine; all AI tools read and write it
  • ContextGraph — build a knowledge graph of your codebase once, answer structural questions in ~500 tokens instead of ~50,000

Real measured reduction on this project: 162× fewer tokens, 99.38% reduction per conversation.


Installation

npm install -g context-mcp-server

Requires Node.js ≥ 18. Installs context-mcp, context-mcp-http, and the ctx CLI.

ContextGraph requires uv (Python runner). Memory tools work without it.

# macOS / Linux
curl -Ls https://astral.sh/uv/install.sh | sh

# Windows
winget install astral-sh.uv

Quick Start

Run from your project root:

ctx install --initial

This installs Node.js + Python (ContextGraph) dependencies. Run once after installing the npm package.

Then write MCP config + AI instruction files:

ctx install --all

To install for a specific platform only:

ctx install --claude      # Claude Code
ctx install --cursor      # Cursor
ctx install --vscode      # VS Code Copilot
ctx install --gemini      # Gemini CLI
ctx install --codex       # Codex CLI
ctx install --windsurf    # Windsurf

For Codex project installs, ctx install --codex writes:

  • .codex/config.toml with [mcp_servers.context-mcp] MCP configuration.
  • AGENTS.md with Context-MCP usage rules for Codex.
  • .codex/hooks/ pre/post shell hook scripts for project-local Codex sessions.

For web clients (Claude.ai, ChatGPT), start the HTTP server:

ctx online               # start in background, prints OAuth credentials + URL
ctx online --restart     # force restart
ctx online --port 3200   # different port

CLI Reference

Both ctx and context are aliases for the same CLI.

ctx                            # interactive mode (UI)

# Context
ctx list [project]             # list entries by tree: graph / context / summary / plans
ctx projects                   # all projects with graph status + recent entries
ctx search "query"             # keyword → semantic fallback search
ctx add                        # add entry interactively
ctx summary [project]          # summarize recent entries

# Delete
ctx delete <id-prefix>         # delete one entry
ctx delete project <name>      # delete all entries for a project

# Server
ctx online                     # start HTTP server (idempotent)
ctx online --restart           # force stop + restart
ctx settings                   # view and edit config interactively

# Install
ctx install --initial          # install / update Node.js + Python deps
ctx install --all              # write config + rules for all platforms

Security

File and git tools are sandboxed to your project root. Pass rootPath when calling context.resume:

{ "action": "resume", "project": "my-app", "rootPath": "/home/user/my-app" }

Any file or git operation outside that directory is rejected. Applies to all HTTP-connected clients.


Features

Memory

  • context.resume — loads recent entries, active plans, and graph status; registers rootPath for sandboxing
  • context.save — store context with 4 types: decision, bug, note, config
  • context.get / context.update / context.delete — full CRUD, single or batch
  • search — keyword-first, semantic fallback
  • plan — auto-triggered when AI makes any plan; saves a markdown summary to a planDir you specify
  • Auto-deduplication on save; auto-compact at 20 entries → stored in summary.json

ContextGraph

Also called CodeGraph. MCP tools use the codegraph_* prefix — both names mean the same thing.

Step 1 — Build (once per project, runs locally, no API cost):

codegraph_build(path)

Parses codebase via tree-sitter AST (16 languages, regex fallback). Extracts functions, classes, imports, and call edges. Automatically generates visualizations on every build. Metadata saved to <project>/codegraph-cache/.

Step 2 — Query (instant, forever):

codegraph_arch(path, limit?)              → module map: every file, its exports, its imports
codegraph_query(path, question?, node?)   → structural question OR single-node lookup (or both)
codegraph_nodes(path, type)               → list all nodes of a type
codegraph_report(path)                    → god nodes, clusters, surprising connections
codegraph_affected(path, node, depth?)    → BFS blast radius — what breaks if you change X?

codegraph_query accepts question (natural language), node (exact/partial name), or both. Use before reading any files.

Step 3 — Visualize (auto-generated on every build):

codegraph_html(path, formats?)            → regenerate visualizations on demand

Every codegraph_build automatically writes to <project>/codegraph-cache/:

  • graph.html — interactive vis.js force graph (dark theme, search, community toggle)
  • tree.html — D3 collapsible file hierarchy
  • callflow.html — Mermaid architecture diagrams per community
  • graph.graphml — Gephi / yEd export
  • obsidian/ — per-node .md vault with [[wikilinks]]

File & Git Tools

Available to HTTP-connected clients (Claude.ai, ChatGPT). Local AI clients use their native IDE tools.

  • read_file, write_file, patch_file, create_dir, list_dir, delete_file
  • git_status, git_diff, git_log, git_add, git_commit, git_push, git_pull, git_branch, git_stash, git_reset, git_show

Enable git tools with --access-git flag or access_git: true in config.


Server Flags

context-mcp [--data-dir <path>]

context-mcp-http [--port <number>] [--host <string>] [--access-git] [--data-dir <path>]

Default port: 3100. Default data dir: ~/.context-mcp.


Config Reference

~/.context-mcp/contextconfig.json — auto-created on first run:

FieldDefaultDescription
client_id"context-mcp"OAuth client ID
client_secretauto-generatedOAuth signing secret
port3100HTTP server port
host"localhost"HTTP bind host
access_gitfalseEnable git tools for HTTP clients
public_urlnullPublic URL for ctx online output
allowed_redirect_uris["https://claude.ai"]OAuth redirect URI whitelist
allowed_origins[]Extra CORS origins

Edit with ctx settings.


License

MIT

Ver o original no GitHub

Bom para

Relacionados