DOCSEARCHbyAlgolia
Submit Docs

Context+

repository·main·Indexed 24 days ago

https://github.com/forloopcodes/contextplus

An MCP (Model Context Protocol) server providing semantic intelligence for large-scale engineering. It utilizes AST parsing, RAG, and graph-based memory to enable AI coding agents to navigate and analyze complex codebases. Features include 17 specialized tools for discovery, analysis, code operations, version control, and memory management, supporting embedding providers such as Ollama and OpenAI-compatible APIs.

Tokens
16.2K
Snippets
15
Records
80
Agent score
83%

What's inside contextplus

  1. Manage Long-Term Memory with Memory Graph Tools

    main

    Context+ includes a Retrieval-Augmented Generation (RAG) system via a memory graph. Agents should use these tools to build cumulative knowledge across sessions.

    • search_memory_graph: Use at the start of every task to retrieve prior context.
    • upsert_memory_node: Use after completing work to persist learnings (concepts, files, symbols, or notes).
    • create_relation: Use to create typed edges (e.g., depends_on, implements) between nodes.
    • add_interlinked_context: Bulk-add nodes with auto-similarity linking (cosine similarity $\ge 0.72$).
    • retrieve_with_traversal: Start from a node and walk outward to return scored neighbors based on decay and depth.
    • prune_stale_links: Periodically remove decayed edges and orphan nodes.

  2. Use the PMLL short-term KV memory `peek()` pattern

    main

    To avoid redundant, expensive MCP tool calls and accelerate execution, use the PMLL short-term KV memory tools (provided by pmll-memory-mcp) to cache results. Follow this lifecycle pattern:

    1. init: Call once at the start of a task to set up the session silo and Q-promise chain.
    2. peek: Call before every expensive tool invocation. If it's a hit, use the cached value; if it's pending, wait on the Q-promise.
    3. set: After a cache miss, use this to store the result in the silo for future subtasks.
    4. resolve: Use this to check or fulfill Q-promise continuations when a peek returns a pending status.
    5. flush: Call at the end of the task to clear all session slots.

  3. Use the Context+ MCP Toolset for Codebase Exploration

    main

    The Context+ MCP server provides 17 tools designed to allow agents to navigate and understand codebases structurally without reading every file. Use these tools following the recommended workflow to conserve context.

    Recommended Workflow

    1. Scoping: Start with get_context_tree and get_file_skeleton to map files and symbols.
    2. Discovery: Use semantic_navigate to browse by meaning or semantic_code_search to find files by concept.
    3. Deep Dive: Use semantic_identifier_search to find specific definitions and call chains.
    4. Impact Analysis: Before modifying or deleting symbols, run get_blast_radius to see usage across the codebase.
    5. Validation: After edits, run run_static_analysis to catch errors.
    6. Persistence: Use propose_commit as the only way to save files.

  4. Include paths excluded by .gitignore

    main

    If your workspace .gitignore excludes sub-directories that you still want indexed (e.g., repos/, packages/, or vendor/), you can include them using the --include flag or the CONTEXTPLUS_EXTRA_ROOTS environment variable.

    Each included path is walked independently of the workspace root and respects its own .gitignore.

    Using CLI flags

    bunx contextplus /path/to/workspace \
  --include repos/lacuna \
  --include repos/graphrag-core

    Using Environment Variables

    Use a system path separator (: on Unix, ; on Windows):

    CONTEXTPLUS_EXTRA_ROOTS=repos/lacuna:repos/graphrag-core \
  bunx contextplus /path/to/workspace

    Using MCP Config (Recommended)

    In your .mcp.json, use the env block:

    {
  "mcpServers": {
    "contextplus": {
      "command": "bunx",
      "args": ["contextplus", "/path/to/workspace"],
      "env": {
        "CONTEXTPLUS_EXTRA_ROOTS": "repos/lacuna:repos/graphrag-core"
      }
    }
  }
}

  5. Follow Strict Code Formatting and Abstraction Rules

    main

    When writing or refactoring code using Context+, adhere to these strict structural and formatting constraints:

    File Header (Mandatory)

    Every file MUST start with exactly 2 comment lines (10 words each):

    // Line 1: What the file does
// FEATURE: <name> - The primary feature it belongs to

    Code Organization

    1. Zero Comments: No inline comments, block comments, or TODOs allowed except the header.
    2. Strict Ordering: Imports $\rightarrow$ Enums $\rightarrow$ Interfaces/Types $\rightarrow$ Constants $\rightarrow$ Functions/Classes.
    3. Abstraction Thresholds:
      • < 20 lines, used once: Inline it.
      • < 20 lines, used multiple times: Extract to a function.
      • > 30 lines: Extract to its own function or file.
      • Max Nesting: 3-4 levels.
      • Max File Length: 500-1000 lines.
      • Max Files per Directory: 10.

    Variable Discipline

    • Avoid redundant intermediate variables; use call chaining (e.g., c = g(f(a))) unless the variable represents a distinct, meaningful state.
    • Remove all unused variables, imports, and files before finishing.

  6. Generate MCP configuration for specific IDEs

    main

    You can automatically generate the required MCP configuration file for your specific coding agent using the init subcommand. Supported targets include claude, cursor, vscode, windsurf, and opencode.

    npx -y contextplus init claude
bunx contextplus init cursor
npx -y contextplus init opencode

  7. Replace native search and read tools with Context+ structural tools

    main

    To maintain structural awareness of the codebase, you MUST use Context+ tools instead of standard shell or file commands. Use the following mapping:

    • Instead of grep, rg, ripgrep: Use semantic_code_search to find code by meaning.
    • Instead of find, ls, glob: Use get_context_tree to get structure with symbols and line ranges.
    • Instead of cat, head, or reading files: Use get_file_skeleton first to get signatures without the full body.
    • Instead of manual symbol tracing: Use get_blast_radius to trace all usages across the codebase.
    • Instead of keyword search: Use semantic_identifier_search for ranked definitions and call chains.
    • Instead of directory browsing: Use semantic_navigate to browse by meaning.

  9. Quick Start Context+ via npx or bunx

    main

    Context+ is an MCP server that can be added to your IDE's MCP configuration without manual installation. It provides semantic intelligence for large-scale engineering by combining RAG, AST parsing, and graph-based linking.

    For Claude Code, Cursor, and Windsurf

    Add the following to your mcpServers configuration:

    {
  "mcpServers": {
    "contextplus": {
      "command": "bunx",
      "args": ["contextplus"],
      "env": {
        "OLLAMA_EMBED_MODEL": "nomic-embed-text",
        "OLLAMA_CHAT_MODEL": "gemma2:27b",
        "OLLAMA_API_KEY": "YOUR_OLLAMA_API_KEY"
      }
    }
  }
}

    For VS Code

    Add the following to your .vscode/mcp.json:

    {
  "servers": {
    "contextplus": {
      "type": "stdio",
      "command": "bunx",
      "args": ["contextplus"],
      "env": {
        "OLLAMA_EMBED_MODEL": "nomic-embed-text",
        "OLLAMA_CHAT_MODEL": "gemma2:27b",
        "OLLAMA_API_KEY": "YOUR_OLLAMA_API_KEY"
      }
    }
  },
  "inputs": []
}

    Using npx

    If you prefer npx, use "command": "npx" and "args": ["-y", "contextplus"].

  10. Run the landing page development server

    main

    To start the local development environment for the landing package, use your preferred package manager to run the dev script. Once running, the application is accessible at http://localhost:3000.

    npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev

  11. Configure Context+ MCP Environment Variables

    main

    The Context+ MCP server uses several environment variables to configure its embedding engine and tracking behavior. These settings primarily interact with Ollama for vector embeddings and chat capabilities.

    VariableDefaultDescription
    OLLAMA_EMBED_MODELnomic-embed-textEmbedding model name
    OLLAMA_API_KEY(empty)Cloud auth (auto-detected by SDK)
    OLLAMA_CHAT_MODELllama3.2Chat model for cluster labeling
    CONTEXTPLUS_EMBED_BATCH_SIZE8Embedding batch per GPU call (hard-capped to 5-10)
    CONTEXTPLUS_EMBED_TRACKERtrueEnable realtime embedding updates for changed files/functions
    CONTEXTPLUS_EMBED_TRACKER_MAX_FILES8Max changed files per tracker tick (hard-capped to 5-10)
    CONTEXTPLUS_EMBED_TRACKER_DEBOUNCE_MS700Debounce before applying tracker refresh

  12. Configure Embedding Providers

    main

    Context+ supports two embedding backends via the CONTEXTPLUS_EMBED_PROVIDER environment variable.

    Ollama (Default)

    Best for free, offline, and private use. Requires a local Ollama server.

    ollama pull nomic-embed-text
ollama serve

    OpenAI-compatible (Gemini, OpenAI, Groq, vLLM)

    Set CONTEXTPLUS_EMBED_PROVIDER to openai. This allows using any endpoint implementing the OpenAI Embeddings API.

    Google Gemini (Free Tier) Example

    {
  "mcpServers": {
    "contextplus": {
      "command": "npx",
      "args": ["-y", "contextplus"],
      "env": {
        "CONTEXTPLUS_EMBED_PROVIDER": "openai",
        "CONTEXTPLUS_OPENAI_API_KEY": "YOUR_GEMINI_API_KEY",
        "CONTEXTPLUS_OPENAI_BASE_URL": "https://generativelanguage.googleapis.com/v1beta/openai",
        "CONTEXTPLUS_OPENAI_EMBED_MODEL": "text-embedding-004"
      }
    }
  }
}

    Standard OpenAI Example

    {
  "mcpServers": {
    "contextplus": {
      "command": "npx",
      "args": ["-y", "contextplus"],
      "env": {
        "CONTEXTPLUS_EMBED_PROVIDER": "openai",
        "OPENAI_API_KEY": "sk-...",
        "OPENAI_EMBED_MODEL": "text-embedding-3-small"
      }
    }
  }
}

    Note: The semantic_navigate tool uses a chat model for cluster labeling. When using the openai provider, you can set CONTEXTPLUS_OPENAI_CHAT_MODEL (defaults to gpt-4o-mini).