Пишем свой MCP Server: создаём уникальную способность для Claude Code

Создаём MCP Server для управления контекстом проекта с нуля на TypeScript — логирование решений, управление задачами, поиск между сессиями, регистрация инструментов, ресурсы, отладка и публикация.

В предыдущих трёх статьях о MCP мы подключали готовые решения — существующие MCP-серверы, базы данных, внутренние API. Эта статья — совсем другое: мы с нуля построим собственный MCP Server, который делает то, чего не умеет ни один существующий инструмент.

Не оборачиваем чужой API, а пишем свою логику.

Что будем делать: менеджер контекста проекта

У Claude Code есть практическая проблема: он не запоминает ничего между сессиями. Каждый раз, открывая новый чат, приходится заново объяснять контекст проекта, последние решения, текущие задачи. CLAUDE.md частично помогает, но он статичен и не обновляется автоматически по ходу проекта.

Мы создадим MCP Server, который позволит Claude:

  • Записывать проектные решения и контекст («Мы решили использовать Redis для кеширования, потому что X»)
  • Управлять списком задач и их статусами
  • Извлекать ранее сохранённый контекст в новых сессиях

Данные хранятся в локальном JSON-файле, никакие внешние сервисы не нужны.

Инициализация проекта

mkdir mcp-project-context && cd mcp-project-context
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node

tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*"]
}

В package.json добавьте "type": "module".

Слой данных

Начнём с чтения и записи данных. Всё хранится в файле .claude/project-context.json в корне проекта.

src/store.ts:

import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
import { dirname } from "path";

export interface Decision {
  id: string;
  title: string;
  content: string;
  tags: string[];
  createdAt: string;
}

export interface Task {
  id: string;
  title: string;
  status: "todo" | "in-progress" | "done";
  notes: string;
  createdAt: string;
  updatedAt: string;
}

export interface ProjectContext {
  decisions: Decision[];
  tasks: Task[];
}

export class Store {
  private data: ProjectContext;

  constructor(private filePath: string) {
    this.data = this.load();
  }

  private load(): ProjectContext {
    if (!existsSync(this.filePath)) {
      return { decisions: [], tasks: [] };
    }
    return JSON.parse(readFileSync(this.filePath, "utf-8"));
  }

  private save(): void {
    const dir = dirname(this.filePath);
    if (!existsSync(dir)) {
      mkdirSync(dir, { recursive: true });
    }
    writeFileSync(this.filePath, JSON.stringify(this.data, null, 2));
  }

  // Decisions
  addDecision(title: string, content: string, tags: string[]): Decision {
    const decision: Decision = {
      id: crypto.randomUUID().slice(0, 8),
      title,
      content,
      tags,
      createdAt: new Date().toISOString(),
    };
    this.data.decisions.push(decision);
    this.save();
    return decision;
  }

  searchDecisions(query: string): Decision[] {
    const q = query.toLowerCase();
    return this.data.decisions.filter(
      (d) =>
        d.title.toLowerCase().includes(q) ||
        d.content.toLowerCase().includes(q) ||
        d.tags.some((t) => t.toLowerCase().includes(q))
    );
  }

  listDecisions(): Decision[] {
    return this.data.decisions;
  }

  // Tasks
  addTask(title: string): Task {
    const task: Task = {
      id: crypto.randomUUID().slice(0, 8),
      title,
      status: "todo",
      notes: "",
      createdAt: new Date().toISOString(),
      updatedAt: new Date().toISOString(),
    };
    this.data.tasks.push(task);
    this.save();
    return task;
  }

  updateTask(
    id: string,
    updates: Partial<Pick<Task, "status" | "notes" | "title">>
  ): Task | null {
    const task = this.data.tasks.find((t) => t.id === id);
    if (!task) return null;
    Object.assign(task, updates, { updatedAt: new Date().toISOString() });
    this.save();
    return task;
  }

  listTasks(status?: Task["status"]): Task[] {
    if (status) {
      return this.data.tasks.filter((t) => t.status === status);
    }
    return this.data.tasks;
  }
}

Несколько проектных решений:

  • ID — первые 8 символов UUID, достаточно короткие, чтобы их можно было назвать вслух («обнови задачу a3f2b1c9»)
  • Каждая операция записи немедленно сохраняется на диск, без кеширования в памяти
  • Структура данных намеренно простая — ровно столько, сколько нужно

Регистрация инструментов

src/index.ts:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
import { Store } from "./store.js";

const CONTEXT_FILE =
  process.env.CONTEXT_FILE || ".claude/project-context.json";
const store = new Store(CONTEXT_FILE);

const server = new McpServer({
  name: "project-context",
  version: "1.0.0",
});

// ---- Управление решениями ----

server.tool(
  "record_decision",
  "记录一条项目决策。当团队做出技术选型、架构决定、或重要的设计取舍时使用",
  {
    title: z.string().describe("决策标题，如「缓存方案选型」"),
    content: z.string().describe("决策内容和原因"),
    tags: z
      .array(z.string())
      .optional()
      .default([])
      .describe("标签，便于后续检索，如 [\"cache\", \"architecture\"]"),
  },
  async ({ title, content, tags }) => {
    const decision = store.addDecision(title, content, tags);
    return {
      content: [
        {
          type: "text",
          text: `已记录决策 [${decision.id}]: ${decision.title}`,
        },
      ],
    };
  }
);

server.tool(
  "search_decisions",
  "搜索已记录的项目决策。当需要回顾之前为什么做某个选择时使用",
  {
    query: z.string().describe("搜索关键词，会匹配标题、内容和标签"),
  },
  async ({ query }) => {
    const results = store.searchDecisions(query);
    if (results.length === 0) {
      return {
        content: [{ type: "text", text: `没有找到与「${query}」相关的决策` }],
      };
    }
    return {
      content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
    };
  }
);

server.tool(
  "list_decisions",
  "列出所有已记录的项目决策",
  {},
  async () => {
    const decisions = store.listDecisions();
    return {
      content: [{ type: "text", text: JSON.stringify(decisions, null, 2) }],
    };
  }
);

// ---- Управление задачами ----

server.tool(
  "add_task",
  "添加一个待办任务",
  {
    title: z.string().describe("任务标题"),
  },
  async ({ title }) => {
    const task = store.addTask(title);
    return {
      content: [
        { type: "text", text: `已添加任务 [${task.id}]: ${task.title}` },
      ],
    };
  }
);

server.tool(
  "update_task",
  "更新任务的状态或备注",
  {
    id: z.string().describe("任务 ID"),
    status: z
      .enum(["todo", "in-progress", "done"])
      .optional()
      .describe("新状态"),
    notes: z.string().optional().describe("备注信息"),
    title: z.string().optional().describe("更新标题"),
  },
  async ({ id, status, notes, title }) => {
    const task = store.updateTask(id, { status, notes, title });
    if (!task) {
      return {
        content: [{ type: "text", text: `找不到任务 ${id}` }],
        isError: true,
      };
    }
    return {
      content: [{ type: "text", text: JSON.stringify(task, null, 2) }],
    };
  }
);

server.tool(
  "list_tasks",
  "列出任务。可以按状态筛选",
  {
    status: z
      .enum(["todo", "in-progress", "done"])
      .optional()
      .describe("按状态筛选，不传则列出全部"),
  },
  async ({ status }) => {
    const tasks = store.listTasks(status);
    return {
      content: [{ type: "text", text: JSON.stringify(tasks, null, 2) }],
    };
  }
);

// ---- Запуск ----

const transport = new StdioServerTransport();
server.connect(transport);

Регистрация Resource

Помимо инструментов, MCP поддерживает Resource — данные, которые Claude может считывать по своей инициативе. Зарегистрируем «сводку по проекту» как Resource, чтобы Claude получал полный контекст в начале сессии:

server.resource("project-summary", "project://summary", async (uri) => {
  const decisions = store.listDecisions();
  const tasks = store.listTasks();
  const activeTasks = tasks.filter((t) => t.status !== "done");

  const summary = {
    totalDecisions: decisions.length,
    recentDecisions: decisions.slice(-5),
    activeTasks,
    completedTasks: tasks.filter((t) => t.status === "done").length,
  };

  return {
    contents: [
      {
        uri: uri.href,
        mimeType: "application/json",
        text: JSON.stringify(summary, null, 2),
      },
    ],
  };
});

Разница между Resource и Tool: Tool — это то, что Claude вызывает по ходу диалога по мере необходимости; Resource — статический контекст, который Claude может прочитать, как динамически генерируемый аналог CLAUDE.md.

Сборка и настройка

npx tsc

Настройка Claude Code:

{
  "mcpServers": {
    "project-context": {
      "command": "node",
      "args": ["/path/to/mcp-project-context/dist/index.js"],
      "env": {
        "CONTEXT_FILE": "/path/to/your-project/.claude/project-context.json"
      }
    }
  }
}

Перезапустите Claude Code и введите /mcp, чтобы убедиться, что project-context появился в списке.

Практическое использование

После настройки диалог с Claude будет выглядеть так:

Запись решения

Мы только что обсудили и решили использовать Bull + Redis для очереди задач,
а не RabbitMQ. Основная причина — команда уже работает с Redis
и не хочет добавлять новую инфраструктуру. Запиши это.

→ Claude вызывает record_decision
→ Записано решение [a3f2b1c9]: Выбор очереди задач: Bull + Redis

Поиск между сессиями

В новой сессии:

Почему мы тогда выбрали Bull, а не RabbitMQ?

→ Claude вызывает search_decisions("Bull")
→ Находит предыдущую запись, полностью пересказывает причины решения

Трекинг задач

Нужно сделать три вещи:
1. Реализовать эндпоинт регистрации пользователей
2. Написать шаблон письма для регистрации
3. Добавить подтверждение email

→ Claude вызывает add_task три раза
→ Создаются три задачи со статусом todo

Эндпоинт регистрации готов, обнови статус

→ Claude вызывает update_task(id, "done")
→ Заодно выводит оставшиеся задачи со статусом todo

Важные моменты при разработке MCP Server

После создания этого сервера — несколько практических выводов.

Ошибки должны быть понятными

Когда MCP-инструмент возвращает ошибку, Claude зачитывает её пользователю. Поэтому сообщения об ошибках должны быть написаны по-человечески:

// Плохо
throw new Error("ENOENT");

// Хорошо
return {
  content: [{ type: "text", text: `找不到任务 ${id}，用 list_tasks 查看所有任务` }],
  isError: true,
};

isError: true сообщает Claude, что вызов завершился неудачей, и он скорректирует дальнейшее поведение (например, попробует другой подход).

Не перегружайте количеством инструментов

5–10 инструментов на один MCP Server — разумный диапазон. Больше 15 — и вероятность того, что Claude выберет не тот инструмент, заметно растёт. Если функциональности слишком много, разбейте на несколько серверов.

Возвращайте информативные ответы

Вернуть «операция выполнена» — недостаточно. Claude нужно знать результат операции, чтобы продолжить диалог:

// Плохо
return { content: [{ type: "text", text: "OK" }] };

// Хорошо
return { content: [{ type: "text", text: `已添加任务 [${task.id}]: ${task.title}` }] };

Используйте zod для валидации параметров

MCP SDK нативно поддерживает zod. С его помощью можно не только проверять типы параметров, но и через .describe() давать Claude инструкции по использованию. Параметры без описания Claude придётся угадывать.

stdio — самый простой способ транспорта

MCP поддерживает два способа транспорта: stdio (стандартный ввод/вывод) и HTTP+SSE. Для локальной разработки stdio вполне достаточно: Claude Code запускает сервер как дочерний процесс и обменивается данными через stdin/stdout.

HTTP+SSE подходит для удалённо развёрнутых серверов — например, централизованных MCP-сервисов внутри компании.

Отладка

MCP Inspector

Anthropic предоставляет инструмент для отладки — MCP Inspector. С ним можно тестировать MCP Server прямо в браузере:

npx @modelcontextprotocol/inspector node dist/index.js

Он запускает веб-интерфейс, где можно вручную вызывать каждый инструмент, просматривать входные и выходные данные, проверять ошибки. Гораздо эффективнее, чем тестировать через Claude Code.

Логирование

stdout у MCP Server занят (используется для JSON-RPC), поэтому console.log использовать нельзя. Для отладочной информации используйте console.error — она пишется в stderr:

console.error("[debug] processing request:", JSON.stringify(params));

Или пишите в файл:

import { appendFileSync } from "fs";

function log(msg: string) {
  appendFileSync("/tmp/mcp-debug.log", `${new Date().toISOString()} ${msg}\n`);
}

Публикация и распространение

Когда ваш MCP Server стабилизировался, есть несколько способов его распространить:

npm-пакет

Добавьте поле bin и shebang, затем опубликуйте в npm:

{
  "name": "@yourcompany/mcp-project-context",
  "bin": {
    "mcp-project-context": "./dist/index.js"
  }
}

В начало dist/index.js добавьте:

#!/usr/bin/env node

Использование:

{
  "mcpServers": {
    "project-context": {
      "command": "npx",
      "args": ["-y", "@yourcompany/mcp-project-context"]
    }
  }
}

Docker

Если у сервера есть внешние зависимости (базы данных, Redis), Docker-образ — более чистый вариант:

{
  "mcpServers": {
    "project-context": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "yourcompany/mcp-project-context"]
    }
  }
}

Обратите внимание на флаг -i — для stdio-транспорта нужно держать stdin открытым.

Что дальше

Пример в этой статье — минимальный, но полноценный MCP Server. На его основе можно развивать во множестве направлений:

  • Добавить таймлайн проекта (автоматически записывать, что делали каждый день)
  • Интегрировать git log (связать коммиты с решениями)
  • Поддержать несколько проектов (один сервер управляет контекстом нескольких проектов)
  • Добавить шаблоны промптов (например, предопределённый формат «ежедневного отчёта по проекту»)

Возможности MCP ограничены только вашей фантазией. Всё, что можно выразить кодом, можно превратить в инструмент для Claude.