mcp-tool-patterns

MCP Tool Patterns — Akashic Context

Tool Registration Pattern

Tools are registered in setupToolHandlers() inside ListToolsRequestSchema handler. Each tool needs: name, description, inputSchema (JSON Schema).

{
  name: "memory_context",
  description: "Get or set working memory (context.json) for a user.",
  inputSchema: {
    type: "object",
    properties: {
      userId: {
        type: "string",
        description: "User identifier (default: 'default')",
      },
      action: {
        type: "string",
        enum: ["get", "set"],
        description: "Get or set working memory",
      },
      data: {
        type: "object",
        description: "Data to set (only for action='set')",
      },
    },
    required: ["action"],
  },
},

Handler Pattern (Zod validation)

All handlers use Zod for input validation:

private async handleMemoryContext(args: unknown) {
  const schema = z.object({
    userId: z.string().optional().default("default"),
    action: z.enum(["get", "set"]),
    data: z.record(z.unknown()).optional(),
  });

  const { userId, action, data } = schema.parse(args);

  // implementation...
}

Adding userId to Existing Tools

Before (hardcoded):

// In constructor
this.manager = new MemoryManager({
  dataDir,
  userId: "mcp-user",   // hardcoded
  workspaceDir: config.workspaceDir,
  // ...
});

After (per-call userId): The manager must be created per-call (or use a manager factory/cache). Pattern: create MemoryManager per userId on demand, cache by userId.

private managers = new Map<string, MemoryManager>();

private getManager(userId: string): MemoryManager {
  if (!this.managers.has(userId)) {
    const manager = new MemoryManager({
      dataDir: this.dataDir,
      userId,
      workspaceDir: this.workspaceDir,  // base dir, manager appends users/{userId}
      memory: this.memoryConfig,
    });
    if (this.embeddingConfig) {
      this.setupEmbeddingProviderForManager(manager, this.embeddingConfig);
    }
    this.managers.set(userId, manager);
  }
  return this.managers.get(userId)!;
}