CueMap MCP Server v0.7.3

A premium MCP bridge for explainable, repository-aware agent memory.

The Model Context Protocol (MCP) server for CueMap, allowing AI coding assistants (like Claude Desktop, Cursor, Windsurf, and Antigravity) to instantly recall codebase context using the CueMap engine.

For agent-facing operating guidance—including repository consent, supported content types, recall modes, accuracy-oriented knob selection, and troubleshooting—see SKILL.md.

Zero-Config Deployment

The CueMap MCP Server is designed to work completely out-of-the-box. When started, it automatically manages a high-performance Rust instance of the CueMap Server in the background. The v0.7.3 engine bundles qint8 MiniLM-L3 by default and q4 MiniLM-L3 for the edge profile; no model download occurs at runtime.

You do not need to install or run the CueMap CLI manually. The correct pre-compiled binary for your operating system is automatically downloaded via optional NPM dependencies. Embedded startup supports Linux x64/ARM64, macOS x64/ARM64, and Windows x64.

Installation

# Global installation makes the `cuemap-mcp` command available
npm install -g cuemap-mcp

(Note: Ensure your package manager is configured to download optionalDependencies so the local Rust binary is included).

Agent Plugin

CueMap also ships a separate cuemap-agent-plugin package for Agent Plugins-compatible clients. It bundles the portable plugin.json manifest, stdio mcp.json configuration, and a repository-memory skill. The plugin launches this MCP server at the matching release version and must be installed or downloaded separately from cuemap-mcp.

Configuration (Environment Variables)

By default, the embedded engine runs on port 8735. You can customize the server behavior by passing the following environment variables in your MCP configuration:

• CUEMAP_PORT: Override the port the embedded engine binds to (default: 8735).
• CUEMAP_CONFIG_PATH: Absolute path to a custom server_config.toml to configure advanced Engine tuning, background jobs, and RAG search parameters.
• CUEMAP_URL: If you prefer to bypass the embedded engine and connect to a remotely hosted or separately running CueMap server, specify its URL here (e.g. http://localhost:8735).
• CUEMAP_PROJECT: Override the default project. Without this setting, CueMap derives a stable repository-scoped project from the current Git remote or working directory.
• CUEMAP_LOG_PATH: Override the embedded engine log path. It defaults to ~/.cuemap/server.log, which is the file read by cuemap logs.

Server lifecycle

The MCP server calls EmbeddedCueMap.start() as soon as Codex launches the plugin process, before any CueMap tool is invoked. It attaches to a compatible engine already listening at CUEMAP_URL or the configured port; otherwise it starts and owns a local engine automatically. cuemap_init does not start the server—it previews or applies a confirmed repository scope after the engine is ready. An engine owned by the MCP process is stopped gracefully when that process exits.

Using with AI Agents

To use this MCP server with your AI assistant, add it to your assistant's MCP configuration file.

Example Configuration (Claude Desktop)

{
  "mcpServers": {
    "cuemap": {
      "command": "npx",
      "args": [
        "-y",
        "cuemap-mcp"
      ],
      "env": {
        "CUEMAP_PORT": "8735"
      }
    }
  }
}

Available Tools

• cuemap_init_preview: Performs a read-only repository metadata scan and returns supported top-level folders/root files, counts, the stable repository project ID, and any existing saved scope. Present this preview to the user before ingestion.

  • path (string): Absolute path to the repository root.
  • projectName (string, optional): Project ID override. Defaults to the stable repository-scoped ID.
  • includedPaths (string[], optional): Repository-relative files or folders to preview. Empty means all supported files allowed by ignore rules.
  • ignoredPatterns (string[], optional): Additional gitignore-style exclusions.
  • ignoredExtensions (string[], optional): Additional excluded extensions.

• cuemap_init: Applies a user-confirmed repository ingestion scope, starts the initial scan, and keeps watching that scope for new, changed, deleted, newly ignored, or newly unignored supported files. It only reports verified completion after observing ingestion activity, reaching a terminal job phase, and completing intent annotation; an initial idle status with 0/0 writes is not considered complete.

  • path (string): Absolute path to the repository root.
  • projectName (string, optional): Project ID override. Defaults to the stable repository-scoped ID.
  • includedPaths (string[], optional): User-approved repository-relative files or folders. Empty means all supported files allowed by ignore rules.
  • ignoredPatterns (string[], optional): Additional gitignore-style exclusions.
  • ignoredExtensions (string[], optional): Additional excluded extensions.
  • confirmed (boolean): Must be true only after explicit user confirmation of the previewed scope.

• cuemap_status: Returns project-scoped background ingestion progress plus derived monitoring fields. Poll it after cuemap_init until verified_complete is true.

  • project (string, optional): Project ID override. Defaults to the stable repository-scoped ID.
  • active: Whether the current phase is non-terminal or writes/intent annotations remain pending.
  • observed_activity: Whether this MCP process has observed an active phase or positive write/intent counts for the project.
  • pending_writes: Remaining writes based on the latest totals.
  • pending_intents: Remaining memory intent annotations based on the latest totals.
  • verified_complete: True only after activity has been observed, the project reaches done or idle, no work failed or remains pending, and intent_ready is not false.

Project inspection and memory lifecycle

• cuemap_projects: List projects and their summary metadata, including whether each project is currently loaded in RAM.
• cuemap_project_load: Explicitly warm a persisted project before a latency-sensitive operation. Ordinary project requests demand-load it when needed.
• cuemap_project_save: Persist a current snapshot without unloading it.
• cuemap_project_unload: Persist and unload a project to reduce memory usage. Active work can produce a retryable busy response.
• cuemap_project_pack / cuemap_project_package_load: Write or load a ready-to-query local .cuemap package.
• cuemap_project_push / cuemap_project_pull: Transfer a package through S3 using the engine host's configured AWS CLI.
• cuemap_project_sync: Fast-forward immutable S3 history and refuse divergence.
• cuemap_stats: Read repository-project statistics, or global engine statistics with global: true.
• cuemap_memory_get: Read one memory as decoded text and provenance by numeric memory_id and owning project. Requires an engine supporting GET /memories/:id?decoded=true; older engines return an upgrade error through this tool.
• cuemap_memory_reinforce: Reinforce one memory, optionally on explicit cues.
• cuemap_memory_delete: Permanently delete one memory. Requires confirmed: true after explicit user confirmation.
• cuemap_project_export: Export a cursor-paginated project page with configurable content, cue, and metadata inclusion.
• cuemap_project_artifacts: Inspect CueBridge artifact metadata without reloading it.

Explicit ingestion

• cuemap_ingest_url: Ingest one URL or recursively crawl it with depth and same_domain_only controls.
• cuemap_ingest_content: Ingest supplied text with filename, source-key, metadata, structural-cue, segmentation, and optional one-vector-per-produced-chunk embeddings.
• cuemap_ingest_file: Ingest one user-approved local file path.

These tools are for explicit ingestion requests. Repository initialization continues to use the preview, confirmation, and watcher workflow above.

Alias and Lexicon administration