MCP Concepts

MCP Protocol Reference (v2025-03-26)

The technical interface exposed by the local-memory-mcp server for AI agents, compliant with the Model Context Protocol (MCP) Specification v2025-03-26.

Server Lifecycle & Capabilities

• Protocol Version: 2025-03-26
• Transport: JSON-RPC 2.0 over standard input/output (stdio).
• Supported Capabilities:
  • tools (list, call)
  • resources (list, read, subscribe, listChanged notifications)
  • prompts (list, get, listChanged notifications)
  • logging (setLevel, message notifications)
  • completions (complete)

Basic Protocol Requirements (JSON-RPC 2.0)

• Requests & Responses: all requests MUST include a valid, non-null id (string or integer) never used before in the active session; all responses MUST include the matching id.
• Notifications: one-way messages MUST NOT include an id field. The receiver must not send a response.
• Schema Validation: all input schemas and tools use JSON Schema draft 2020-12 by default.
• Metadata (_meta): requests and notifications may optionally include a _meta object for progress tracking or out-of-band metadata.
• Authorization: designed for local-first execution over the stdio transport, the MCP Authorization specification (OAuth 2.1) is not applicable. Security is managed via local filesystem permissions and environment-level access.

Lifecycle Management

• Initialization Handshake: the connection begins with an initialize request; the server responds with its capabilities, and the client MUST then send a notifications/initialized notification. No other requests (except ping) are permitted before the handshake completes.
• Liveness (Ping): both sides support the ping method at any time, including during initialization.
• Disconnection: on stdio transports the client gracefully exits by closing the input stream; the server shuts down gracefully.
• Error Handling: if protocol version negotiation fails, the server returns an explicit -32602 error containing the supported and requested versions.

Utilities: Ping, Progress, Cancellation

• Ping: a standard JSON-RPC request with method "ping" and no parameters; the receiver returns "result": {}. If no response arrives within a reasonable timeout, the sender MAY consider the connection stale.
• Progress: requests may include _meta.progressToken; while processing, the server MAY emit notifications/progress carrying the matching token, a strictly increasing progress value, and optionally total or a human-readable message. Tracking ends when the final response is returned.
• Cancellation: clients may send notifications/cancelled with a requestId and optional reason; the server aborts the underlying processing (e.g. SQLite query, vector embeddings, tool execution) and drops the response.

STDIO Transport Requirements

• Encoding & Formatting: all JSON-RPC messages MUST be encoded in UTF-8.
• Delimiters: messages MUST be delimited by a single newline and MUST NOT contain embedded newlines within their payload.
• I/O Channels: the server reads from stdin and writes responses/notifications exclusively to stdout; nothing but valid MCP JSON-RPC messages may be written to stdout.
• Diagnostics & Logging: the server MAY write UTF-8 strings to stderr for logging; output on stderr does not inherently indicate a protocol error.

Client Features: Roots

• The client MUST declare the roots capability during initialization.
• List Request (roots/list): the server MAY request the active workspaces; the client returns an array of Root objects, each with a mandatory uri (using the file:// scheme) and an optional name.
• Notifications (notifications/roots/list_changed): if the client declared roots: { listChanged: true }, it MUST notify the server whenever its workspace boundaries change.

---

1. Tools (Model Control)

Tools are executable functions exposed to the LLM to perform actions, interact with the local SQLite database, or retrieve dynamic data. The server registers 17 canonical tools — legacy dotted names (memory-store, task-create, …) are not registered; their functionality is folded into the unified tools under auto-inferred modes. See the Tool Reference for full usage examples.

Knowledge Management (Memory)

• memory-write: unified write tool — store a new entry (content + type + title; formerly memory-store), update an entry (id/code + fields; formerly memory-update), or acknowledge usage (acknowledge: "used" | "irrelevant" | "contradictory"; formerly memory-acknowledge). Convenience modes: type: "decision" with context/rationale/alternatives (importance-4 decision), type: "task_archive" with key_decisions/next_steps (importance-3 archive).
• memory-read: unified read tool — search (query; formerly memory-search), detail (id/code/ids/codes; formerly memory-detail), or recap (no params; formerly memory-recap).
• memory-delete: soft-delete one or more memory entries (single id or bulk ids).
• synthesize: advanced reasoning tool that synthesizes grounded answers using the client's LLM (formerly memory-synthesize). Only registered when the client declares the sampling capability.
• repo-summarize: update the high-level summary for a repository (formerly memory-summarize).

Task Management

• task-read: unified read tool — list (no params; formerly task-list), detail (id/task_code; formerly task-detail), or search (query).
• task-write: unified write tool — create (phase + title + description; formerly task-create), interactive create (interactive: true), update (id/code; formerly task-update), or bulk (tasks[]). Progresses tasks through backlog → pending → in_progress → completed/canceled/blocked; a comment is required on status changes, and completed gates on children being completed first.
• task-delete: hard deletion of task records (single id or bulk ids).

---

2. Resources (Application Control)

Resources provide read-only access to specialized data views using a repository-scoped URI scheme, with real-time updates via resources/subscribe.

Global Resources

• repository://index — list of all available repositories.
• session://roots — active workspace roots of the current client session.

Repository Resources (Templates)

• repository://{name}/memories — paginated list of active memories for a repository.
• repository://{name}/memories?search={search}&type={type}&tag={tag} — filtered memory list.
• memory://{id} — direct access to a memory entry (full details and statistics) by UUID.
• repository://{name}/summary — high-level global summary/signal for a repository.
• repository://{name}/tasks — paginated list of tasks for a repository.
• repository://{name}/tasks?status={status}&priority={priority} — scoped task list. The priority filter (1–5) uses local-memory-mcp semantics: 1=Low, 2=Normal, 3=Medium, 4=High, 5=Critical — it is not an MCP-specified field.
• task://{id} — direct access to a task (full description and comments) by UUID.
• repository://{name}/actions — paginated stream of agent tool actions logged in a repository.
• action://{id} — direct access to one action audit log entry by integer ID.

Codebase Resources (Templates)

Read-only views over a repo's codebase index. Every read requires the repo to be indexed — otherwise the server returns a RecoverableError ("Repo … not indexed. Run codebase-index on repo.").

• codebase://{repo}/symbols — symbol records (search, kind, limit, offset query params; mirrors the SEARCH mode of codebase-read).
• codebase://{repo}/symbols?search={search}&kind={kind}&limit={limit} — filtered/paginated forms, registered as separate templates.
• codebase://{repo}/symbols/{name} — full trace payload for one symbol (definition, references, export chain, parent/children; mirrors the TRACE mode of codebase-read). Ambiguous names return a disambiguation payload; a missing symbol returns the -32002 resource-not-found error.
• codebase://{repo}/files/{file_path} — file landmark: indexed file metadata (path, language, checksum, line count, size, last indexed) plus its symbols. Raw file content is not served (disk-only, never stored — payload carries content: null); use the CODE mode of codebase-read (with repoPath) to grep file contents.

All codebase:// reads are strictly read-only and DB-flat: payloads contain symbols and spans only, never raw content.

---

3. Prompts (User Control)

Prompts are predefined instruction templates that guide model interactions. Not all coding agents support MCP prompts:

Agent	MCP Prompts	Notes
Claude Desktop	✅ Supported	Prompts appear as slash commands
Claude Code	✅ Supported	Invoked as /mcp__servername__promptname
Cursor	✅ Supported	Prompts supported, Resources NOT supported
Windsurf	✅ Supported	All three: Tools, Prompts, Resources
GitHub Copilot (VS Code)	✅ Supported	Use /<server>.<prompt> in chat
Continue.dev	✅ Supported	Surfaces as slash commands in agent mode
Zed	✅ Supported	As slash commands
Gemini CLI	✅ Supported
Codex CLI (OpenAI)	❌ Not Supported	Only Tools + Resources
Cline	❌ Not Supported	Only Tools + Resources

If your agent doesn't support prompts, invoke the equivalent behavior via Tools (e.g. prompt memory-agent-core instructions manually) or use the Dashboard UI.

Core Lifecycle Prompts

• memory-agent-core — essential behavioral contract for any memory-aware agent.
• project-briefing — onboarding template for starting a new session in a repository.

Specialized Workflow Prompts

• task-management-guidelines — task lifecycle and coordination contract for complex multi-task initiatives (replaces the legacy task-orchestrator prompt, which is not registered).
• senior-code-review — high-standard review template focused on project-specific patterns.
• root-cause-analysis — debugging template for tracing bugs back to their origin.

---

4. Advanced Capabilities Support

• Completions: supported via completion/complete for autocompletion of prompt arguments (ref/prompt) and resource arguments (ref/resource) — not tool inputs.
• Logging: dynamic log level adjustment via logging/setLevel, structured logs via notifications/message.
• Sampling: uses the sampling/createMessage client capability to generate synthesized memory summaries (the synthesize tool).
• Elicitation: uses the elicitation/create client capability (form or url mode) for interactive task creation forms.

⚠️ No Warranty

The MCP interface and responses are provided "AS IS" without any warranty.

Related Pages

• Getting Started — install and register the server
• Tool Reference & Usage Guide — tool usage and examples
• Referensi Protokol MCP — Bahasa Indonesia