How to Implement New MCP Tools in the Claude-Mem Plugin Framework

To implement new MCP tools in the Claude-Mem plugin framework, define a tool schema in the MCP server's tools array and implement a corresponding Worker HTTP endpoint that handles the business logic.

The Claude-Mem plugin framework exposes its Memory-Context Protocol (MCP) through a lightweight HTTP wrapper, allowing developers to extend functionality by adding new tools. This guide walks through the exact implementation pattern used in the thedotmack/claude-mem repository, referencing specific source files and line numbers to ensure technical accuracy.

Understanding the MCP Architecture in Claude-Mem

The framework separates concerns between the MCP protocol layer and business logic execution. This separation allows tools to remain portable while the heavy processing occurs in a dedicated Worker process.

The MCP Server Wrapper

The MCP server implementation lives in src/servers/mcp-server.ts. This file defines the tools array starting at line 57, where each tool is registered as an object containing name, description, inputSchema, and handler properties.

The server registers two critical request handlers:

• ListToolsRequestSchema (line 57-66): Returns the complete tool catalogue to clients
• CallToolRequestSchema (line 88-98): Receives tool invocations, looks up the requested tool in the array, and executes its handler function

Before accepting requests, the server verifies Worker availability through verifyWorkerConnection() at lines 42-50, ensuring the HTTP API is ready to receive forwarded requests.

The Worker HTTP API

The Worker process, managed by src/services/worker-service.ts, exposes an independent HTTP API where actual tool logic executes. Routes are organized under src/services/worker/*, with each domain (search, observations, etc.) having its own subdirectory.

When an MCP tool's handler executes, it simply forwards arguments to the Worker via HTTP GET or POST requests, then returns the Worker's response to the MCP client.

Step-by-Step Guide to Implement New MCP Tools

Adding a new tool requires modifications to both the MCP server definition and the Worker API implementation.

Step 1: Define the MCP Tool Schema

Edit src/servers/mcp-server.ts to add a new entry to the tools array. Each tool requires:

• name: Unique identifier using snake_case
• description: Clear explanation of functionality for LLM context
• inputSchema: JSON Schema defining required parameters
• handler: Async function forwarding to Worker API

// src/servers/mcp-server.ts (add to tools array)
{
  name: 'summarize_observation',
  description: 'Generate a concise TL;DR for a single observation ID.',
  inputSchema: {
    type: 'object',
    properties: {
      id: { 
        type: 'number', 
        description: 'Observation ID to summarize' 
      }
    },
    required: ['id'],
    additionalProperties: false
  },
  handler: async (args: any) => {
    return await callWorkerAPIPost('/api/observations/summarize', args);
  }
}

Step 2: Implement the Worker Endpoint

Create or modify files in src/services/worker/ to handle the business logic. The endpoint should parse incoming requests, execute database queries or external calls, and return properly formatted MCP content.

// src/services/worker/observations/summarize.ts
import { Router } from 'express';
import { getDb } from '../../infrastructure/Database.js';
import { logger } from '../../utils/logger.js';

export const router = Router();

router.post('/api/observations/summarize', async (req, res) => {
  const { id } = req.body;
  const db = await getDb();
  const obs = await db.getObservation(id);
  
  if (!obs) {
    return res.status(404).json({ error: 'Observation not found' });
  }

  // Simple summarization – replace with LLM call if desired
  const summary = obs.text.slice(0, 200) + 
    (obs.text.length > 200 ? '…' : '');
  
  logger.info('WORKER', 'Summarized observation', { id });
  
  res.json({ 
    content: [{ type: 'text', text: summary }] 
  });
});

Step 3: Register the Route in the Worker Server

Import and mount the new router in the main Worker server file to activate the endpoint.

// src/services/worker/WorkerServer.ts
import { router as summarizeRouter } from './observations/summarize.js';

// Add to existing app configuration
app.use(summarizeRouter);

Complete Implementation Example

The following pattern demonstrates the full flow for implementing a custom search tool that queries vector embeddings:

MCP Tool Definition (src/servers/mcp-server.ts):

{
  name: 'semantic_search',
  description: 'Search observations using vector similarity against a query string.',
  inputSchema: {
    type: 'object',
    properties: {
      query: { type: 'string', description: 'Search query text' },
      limit: { type: 'number', description: 'Max results to return', default: 5 }
    },
    required: ['query']
  },
  handler: async (args) => {
    return await callWorkerAPIGet('/api/search/semantic', args);
  }
}

Worker Implementation (src/services/worker/search/semantic.ts):

import { Router } from 'express';
import { getVectorStore } from '../../infrastructure/VectorStore.js';

export const router = Router();

router.get('/api/search/semantic', async (req, res) => {
  const { query, limit = 5 } = req.query;
  const store = await getVectorStore();
  const results = await store.similaritySearch(query as string, Number(limit));
  
  res.json({
    content: results.map(r => ({
      type: 'text',
      text: `[Score: ${r.score}] ${r.text}`
    }))
  });
});

Key Files and Their Roles

Understanding the codebase structure ensures you modify the correct files when extending functionality:

• src/servers/mcp-server.ts – Core MCP protocol wrapper; defines the tools array (lines 57-66) and RPC handlers (lines 88-98). Contains verifyWorkerConnection() (lines 42-50) for health checks.
• src/services/worker-service.ts – Manages the Worker process lifecycle and exposes the HTTP API that MCP tools consume.
• src/services/worker/* – Domain-specific business logic implementations (e.g., search/, observations/). New tool logic belongs here.
• src/utils/logger.ts – Centralized logging utility used across MCP server and Worker processes to trace tool execution.

Summary

• Claude-Mem exposes MCP tools through a thin HTTP wrapper in src/servers/mcp-server.ts that forwards requests to a Worker API.
• To implement new MCP tools, define the tool schema in the MCP server's tools array with a handler that calls the Worker, then implement the corresponding endpoint in src/services/worker/.
• The MCP server handles ListToolsRequestSchema (lines 57-66) and CallToolRequestSchema (lines 88-98), while the Worker contains all business logic, database queries, and vector search operations.
• This separation keeps the MCP layer portable and stateless while allowing complex operations to run in the dedicated Worker process.

Frequently Asked Questions

What is the Memory-Context Protocol (MCP) in Claude-Mem?

The Memory-Context Protocol (MCP) is the interface that allows Claude Code instances to discover and invoke tools provided by the Claude-Mem plugin. According to the thedotmack/claude-mem source code, the MCP server implementation in src/servers/mcp-server.ts exposes a JSON-RPC interface over HTTP, registering handlers for ListToolsRequestSchema and CallToolRequestSchema to catalogue and execute tools respectively.

Do I need to modify the MCP server to add new functionality?

Yes, but only minimally. You must add a new tool definition to the tools array in src/servers/mcp-server.ts (lines 57-66), specifying the name, description, inputSchema, and a handler function. However, the actual business logic should not reside in the MCP server; instead, the handler should forward requests to the Worker HTTP API, keeping the MCP layer thin and protocol-focused.

How does the MCP server communicate with the Worker process?

The MCP server communicates with the Worker via HTTP requests using helper functions like callWorkerAPIPost() and callWorkerAPIGet(). Before accepting tool calls, the server verifies the Worker is healthy through verifyWorkerConnection() (lines 42-50 in src/servers/mcp-server.ts). The Worker process, managed by src/services/worker-service.ts, exposes domain-specific endpoints under src/services/worker/* that handle database queries, vector searches, and other operations requested by MCP tools.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}