MCP Memory Server Surgery

Skill: MCP Memory Server Surgery (Safe Modification)

Scope

This Skill covers changes to MCP servers that expose or mutate the repo memory system, especially:

• tools/mcp/docs-memory/mcp-server.js
• Stdio framing/headerless parsing
• Tool registry shape (tools/list, tools/call) and compatibility

It does not cover:

• Adding unrelated business logic
• Rewriting MCP protocol handling from scratch

Inputs

• What new capability you want (tool name(s), arguments, return shape)
• Backward-compat constraints (do we need to keep old tool names?)
• Validation targets (check scripts, focused tests)

Procedure

1) Retrieve prior art (mandatory)

Use the memory retrieval ritual:

• Skills:
  • mcp_docs-memory_docs_memory_recommendSkills({ topic: "mcp docs-memory server change" })
  • mcp_docs-memory_docs_memory_searchSkills({ query: "docs-memory" })
• Sessions:
  • mcp_docs-memory_docs_memory_searchSessions({ query: "docs-memory mcp-server", maxResults: 10 })

If MCP tools are unavailable, fall back:

• node tools/dev/md-scan.js --dir docs/agi --search "docs-memory" "mcp-server" --json
• node tools/dev/md-scan.js --dir docs/sessions --search "docs-memory" "check-stdio" --json

2) Define the tool contract first

Before coding, write down:

• Tool name: docs_memory_<verbNoun>
• JSON input schema (fields + defaults)
• JSON output schema
• Error modes (missing files, invalid args)

Rule: prefer small composable tools over one mega-tool.

3) Implement with protocol guardrails

• Keep tools/list stable and additive.
• Preserve headerless stdio support (agents/tools may rely on it).
• Avoid introducing long-running server behavior in checks/tests.

4) Validation ladder (non-negotiable)

Run the smallest checks that prove protocol + tool surface:

1. MCP server health (when relevant):
   • node tools/dev/mcp-check.js --quick --json
2. docs-memory stdio compatibility:
   • node tools/mcp/docs-memory/check-stdio.js
3. Focused Jest (add a test if missing):
   • npm run test:by-path tests/tools/__tests__/docs-memory-mcp.test.js

Stop if any step fails; fix before proceeding.

5) Write back into memory (make it cheaper next time)

When the change is done:

• Add/extend a Skill if you introduced a new recurring workflow.
• Record evidence in the active session WORKING_NOTES.md.

Validation (success criteria)

• node tools/mcp/docs-memory/check-stdio.js passes.
• A focused Jest test for the new tool(s) passes.
• docs/agi/AGENT_MCP_ACCESS_GUIDE.md remains accurate for tool names.

References

• MCP access + naming: docs/agi/AGENT_MCP_ACCESS_GUIDE.md
• Skills registry: docs/agi/SKILLS.md
• docs-memory server: tools/mcp/docs-memory/mcp-server.js
• stdio check: tools/mcp/docs-memory/check-stdio.js