Пишемо свій 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.