Практические советы: Я создал сервер MCP, который хранит мой рабочий дневник — вот он

В этом руководстве пошагово описывается процесс создания рабочей системы от сырья до готового решения для проекта «Я создал сервер MCP, который ведет мой рабочий дневник — вот всё, что я узнал». Основное внимание уделяется практическим шагам, четким проверкам и коду, который можно просто скопировать в репозиторий без необходимости догадываться о его назначении. На этапе обзора необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед внесением изменений в код. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии системы. Необходимо одновременно задокументировать успешный сценарий выполнения и сценарий восстановления. Повторные попытки, проверки человеком и обработка ошибок являются неотъемлемой частью продукта, а не элементами последующей доработки.

Что это делает

При работе над этапом «Что оно делает» сначала запишите условия работы: необходимые входные данные, сигнал успешного выполнения и действия при частичной неудаче. Такой список поможет сохранять честность при последующих изменениях кода. Предпочитайте небольшие, тестируемые модули большим скриптам. Когда какой-то шаг терпит неудачу, ошибка должна указывать на конкретную ответственность, а не на запутанную цепочку операций. Записывайте название инструмента, хеш аргументов, время задержки и результат каждого вызова. Без такой информации отладка занимает часы.

## 14:32 #bugfix #websocket
Fixed the race condition in the WebSocket broadcast queue

## 16:10 #testing
Wrote E2E test covering two-client sync

Как создать его (полное руководство)

При работе над разделом «Как создать один этап» сначала запишите контракт: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой список помогает сохранять честность при последующих изменениях кода. Рассматривайте этот этап как контракт между входными данными и проверенными выходными результатами. Дайте названия элементам, определите критерии успеха и не допускайте молчаливого частичного завершения работы. Фиксируйте название инструмента, хеш аргументов, время задержки и результат каждого вызова. Без такой записи отладка занимает часы.

1. Костяк действительно минимален

При работе над этапом «1. Каркас» сначала запишите контракт: необходимые входные данные, сигнал о успехе и действия при частичной неудаче. Такой список помогает сохранять честность при последующих изменениях кода. Записывайте время выполнения и стоимость токенов или запросов рядом с функциональными результатами. Очевидность затрат с самого начала предотвращает неожиданные расходы при переходе с демо-среды в общедоступные среды. Фиксируйте название инструмента, хеш аргументов, задержку и результат каждого вызова. Без такой записи отладка занимает часы. При работе над этапом «1. Каркас» сначала запишите контракт: необходимые входные данные, сигнал о успехе и действия при частичной неудаче. Такой список помогает сохранять честность при последующих изменениях кода. Документируйте одновременно успешный сценарий работы и сценарий восстановления. Повторные попытки, проверки человеком и обработка неработающих сообщений являются частью продукта, а не элементами последующей доработки.

npm install @modelcontextprotocol/server zod

import { McpServer } from '@modelcontextprotocol/server';
import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
import * as z from 'zod/v4';

const server = new McpServer({ name: 'dev-diary', version: '1.0.0' });

server.registerTool(
  'log_work',
  {
    description: 'Append a timestamped entry to the developer diary...',
    inputSchema: z.object({
      text: z.string().min(1),
      tags: z.array(z.string()).optional(),
      date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional(),
    }),
  },
  async ({ text, tags = [], date }) => {
    // ...append to diary/YYYY-MM-DD.md...
    return { content: [{ type: 'text', text: 'Logged.' }] };
  },
);

await server.connect(new StdioServerTransport());

2. Описания представляют собой подсказки, а не документацию

На этапе создания описаний в виде подсказок лучше всего рассматривать их как измеримую основу. Соберите один эталонный пример успешной работы, один пример сбоя и запись о возврате к предыдущему состоянию перед расширением объема работ. Предпочитайте небольшие, проверяемые единицы кода вместо обширных скриптов. При сбое какого-либо шага причина должна быть связана с конкретной ответственностью, а не с запутанной цепочкой операций. Установите лимиты на количество токенов за ход и за сессию. Инструменты агентов активно расширяют контекст; жесткие ограничения предотвращают появление неожиданных счетов.

// ❌ documentation-style
description: 'Appends an entry to the diary.'

// ✅ prompt-style
description: 'Append a timestamped entry to the developer diary for today.
Use this whenever the user says they finished/did/fixed something and
wants it recorded.'

3. Разрабатывайте инструменты вокруг вопросов, а не таблиц

Инструменты дизайна на этом этапе работают лучше всего, когда их рассматривают как измеримую поверхность. Соберите один идеальный пример результата, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объема работ. Рассматривайте этот этап как контракт между входными данными и проверенными результатами. Дайте названия создаваемым элементам, определите критерии успеха и не соглашайтесь на молчаливое частичное выполнение задачи. Используйте инструменты с узкими схемами и четкими метками о побочных эффектах. У операторов должна быть возможность узнать, какие вызовы изменяют состояние, прежде чем они автоматически одобрят их.

Проблема демо-версии (и ее изящное решение)

Демонстрационная проблема и этап работают наилучшим образом, когда рассматриваются как измеримая среда. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объема работ. Записывайте временные показатели, а также стоимость токенов или запросов рядом с функциональными результатами. Отображение стоимости на раннем этапе предотвращает неожиданные счета при переходе от демо-среды к общедоступным средам. Используйте инструменты с узкими схемами и четкими метками о побочных эффектах. Администраторам необходимо знать, какие вызовы изменяют состояние, прежде чем они автоматически одобрят их. Демонстрационная проблема и этап работают наилучшим образом, когда рассматриваются как измеримая среда. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объема работ. Документируйте одновременно успешный путь выполнения и путь восстановления. Повторные попытки, проверки человеком и обработка неработающих сообщений являются частью продукта, а не элементами последующей доработки.

import { Client } from '@modelcontextprotocol/client';
import { StdioClientTransport } from '@modelcontextprotocol/client/stdio';

const transport = new StdioClientTransport({
  command: 'node',
  args: ['dist/server.js'],   // spawns the server as a child process
});
const client = new Client({ name: 'demo-client', version: '1.0.0' });
await client.connect(transport);

// Exactly what Claude Desktop does under the hood:
const { tools } = await client.listTools();
await client.callTool({ name: 'log_work', arguments: {
  text: 'Fixed the race condition in the broadcast queue',
  tags: ['bugfix', 'websocket'],
}});

=== 1. listTools ===
 • log_work — Append a timestamped entry to the developer diary...
 • search_diary — Full-text search across every entry...
 • daily_summary — Everything logged on a given date...
 • stats — Totals, active days, streaks, top tags...

=== 2. log_work x3 ===
Logged to 2026-08-22.md at 19:05 (tags: bugfix, websocket)
...

=== 5. stats ===
📊 1 entries across 2 day(s)
🔥 Streak: 2 consecutive day(s)
🏷️ Top tags: #bugfix (1), #websocket (1)

То, чего не рассказывают в учебниках

При создании шагов в учебниках необходимо заранее определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Лучше использовать небольшие, тестируемые единицы кода вместо обширных скриптов. При сбое шага причина должна быть связана с конкретной функцией, а не с запутанной структурой обработки. Аутентифицируйтесь на входе и повторно авторизуйтесь при работе с данными. Одного только токена не достаточно для обозначения границы использования ресурсов.

Практическое подключение

На этапе реальной интеграции необходимо заранее определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Рассматривайте этот этап как контракт между входными данными и проверенными выходными результатами. Укажите названия элементов, определите критерии успеха и не допускайте молчаливого частичного завершения работы. Проводите аутентификацию на шлюзе и повторно предоставляйте разрешения на уровне данных. Одного только токена-носителя недостаточно для обозначения границы тенантности.

{
  "mcpServers": {
    "dev-diary": {
      "command": "node",
      "args": ["/absolute/path/to/dev-diary-mcp/dist/server.js"],
      "env": { "DIARY_DIR": "/home/you/journal" }
    }
  }
}

Почему Markdown-as-database победил

Чтобы понять, почему Markdown-as-database стал предпочтительным решением, необходимо заранее определить входные данные, ответственного за выполнение шага и критерии завершения перед внесением изменений в код. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Регистрируйте время выполнения и стоимость токенов или запросов вместе с функциональными результатами. Отображение стоимости на раннем этапе предотвращает неожиданные счета при переходе от демо-среды к общедоступным средам. Аутентифицируйтесь у шлюза и повторно авторизуйтесь на уровне данных. Один только токен-носитель не является границей между тенантами. Чтобы понять, почему Markdown-as-database стал предпочтительным решением, необходимо заранее определить входные данные, ответственного за выполнение шага и критерии завершения перед внесением изменений в код. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Документируйте как успешный, так и восстановительный сценарии работы. Повторные попытки, человеческое вмешательство и обработка некорректных сообщений являются частью продукта, а не элементами последующей доработки.

Попробуйте сами

Во время работы на этапе «Попробуйте сами» сначала запишите условия работы: необходимые входные данные, сигнал о успешном выполнении и что происходит при частичной неудаче. Такой чек-лист поможет сохранять честность при последующих изменениях кода. Лучше использовать небольшие, тестируемые единицы кода, чем обширные скрипты. Когда какой-то шаг не срабатывает, причина должна быть связана с конкретной функцией, а не с запутанной цепочкой операций. Зафиксируйте название инструмента, хеш аргументов, время задержки и результат каждого вызова. Без этих данных отладка занимает часы.

git clone https://github.com/rogeriolaa/dev-diary-mcp
cd dev-diary-mcp && npm install && npm run build && npm run demo

Чек-лист операционной деятельности

Этап чек-листа операционной деятельности работает наилучшим образом, когда его рассматривают как измеримую основу. Соберите один эталонный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объема работ.

Храните конфигурацию отдельно от кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь кодовый граф.

Обеспечьте доступ к инструментам с узкими схемами и четкими метками побочных эффектов. У хостов должна быть возможность узнать, какие вызовы изменяют состояние, прежде чем они автоматически согласятся на это.

При наличии бюджета добавьте тест, который проверяет критический путь в процессе CI с использованием фикстчеров, а не реальных платных API.

Документируйте как успешный, так и восстановительный пути работы. Повторные попытки, проверки человеком и обработка неработающих сообщений являются частью продукта, а не дополнительными улучшениями.

Обеспечьте доступ к инструментам с узкими схемами и четкими метками побочных эффектов. У хостов должна быть возможность узнать, какие вызовы изменяют состояние, прежде чем они автоматически согласятся на это.

Перед переходом на новую стек-архитектуру заморозьте версии, сохраните эталонный отчет для критического пути и убедитесь в наличии шагов для отката. В совместных средах необходимы ограничения по скорости запросов, проверки принадлежности и четко определенный ответственный за обновление секретов. Лучше выбирать надежность, чем красивые одноразовые демонстрации.

Примечание к пакету 0f6d55786c75: не храните ключи поставщиков в репозитории, установите лимит токенов на одну сессию и сохраняйте транскрипции рядом с фиксами для оценки, чтобы последующие замены моделей оставались сопоставимыми.