Практычныя прытамулкі: Я створыў сервер 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. Дизайнуйце інструменты навакол пытанняў, а не табэлей

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-як база дадзеных выграў

Кабы з’ясаваць, чаму Markdown-как база дадзэння выграў на данай стадыі, пярш чым зменяць код, неабходна адзначыць вхідныя даны, адпаведальнага за крок і критэрыя завершэння. Аператары должны магчымае перайсці на выкананне кроку з вядомага пункта контролю, не спрабоўваючы здогадвацца пра схованы стан. Запісвайце час выканання і вартасьць токена або запытку праза функцыйнае рэзультат. Відкрытая інформацыя пра вартасьці запобегае неспакоўным рахункам, калі процес пераходзіць з дэмовай среды ў спакульную. Автентыфікуйцеся на в’язку і паўтарна автарызуйцеся на роўні дадзэнняў. Толькі токен-носіцель не є межай адпаведнага тэнанту. Кабы з’ясаваць, чаму Markdown-как база дадзэння выграў на данай стадыі, пярш чым зменяць код, неабходна адзначыць вхідныя даны, адпаведальнага за крок і критэрыя завершэння. Аператары должны магчымае перайсці на выкананне кроку з вядомага пункта контролю, не спрабоўваючы здагадвацца пра схованы стан. Дакументавайце як шлях успеху, так і шлях вярнення да нормы. Перапрыбуткі, людзкія контрольны пункты і обработка некоректных запытак є частью продукту, а не пасляднім дапрацоўкам.

Паспрабуйце

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

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

Чэк-ліст для эксплуатацыі

Стадыя чэк-ліста для эксплуатацыі працюе лепш, калі яе спрыямаць як мерыемую плошчу. Запісайце адну ідеальную версію, адзін прыклад неякосці і прыметкі па адваротным запуску, перш чым расширваць масштаб. Храніце настройкі парадульна ад коду прыемліка. Файлы сяродавішча, хранільнікі секрэтных дадзеных і флагі функций должны знаходзіцца ў аднам месцы, якое аператары можаць пераглядаць без неабяжлівага чытання всей структуры.

Адаптавайце інструменты з вузкімі схемамі та чыткімі пазначэннямі побачных эфектаў. Хостам неабходна знаты, якія запыткі мутуюць стан, прычым яны будуць автаматычна затверджаны.

Калі дозволяе бюджет, дадзіце тэст на перакананне, які працюе з критычным маршрутом у CI за дапамою фікстураў, а не з рэальнымі платнымі API.

Документавайце як штатны, так і патэнціяльны маршруты разам. Перапрыбуткі, людзкія контралі та обработка неканальных паведамленняў є часткай продукту, а не чымсь, што дадаецца пазней.

Адаптавайце інструменты з вузкімі схемамі та чыткімі пазначэннямі побачных эфектаў. Хостам неабходна знаты, якія запыткі мутуюць стан, прычым яны будуць автаматычна затверджаны.

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

Запіскі для пакета 0f6d55786c75: не класты ключі прадаўцоў у репазітарыю, задаць максымальны тэрмін дзейнасці токена на кожную сесію, а таксама зберагчы транскрыпціі празаўсюды з фікстурамі для ацэнкі, каб пазнейшыя замены моделей заставаліся порównанымі.