Галоўная / Артыкулы

Практычныя нататкі: схаваны кошт парады «проста дадайце .mcp.json»

Практычны разбор тэмы «схаваны кошт парады „проста дадайце .mcp.json“»: кантракты, праверкі і гатовыя фрагменты кода для каманд, якія ўкараняюць гэты падыход.

Выдавец: REACTAPP.TOP9 хв чытання2126 слоў

Крыніцы: The hidden cost of ‘just add an .mcp.json’

Наступныя прытамлівкі паказваюць практычны шлях адпрацоўкі тэмы «Закрытыя выкалычкі ‘проста дадзіце .mcp.json’». Акцэнс ставяцца на контракты, пераканання і месца для коду, які можна проста замясціць, а не на мотывацыйныя аспекты. Калі працуеце на стадзіі агляду, спачатку запісайце контракт: неабяжныя даны, сігнал успеху і тое, што выканаецца у разе частковай нявыполненасці. Такі спіс контроля дапамагае залішыцца чыстаснам у пазнейшых змяненах коду. Запісвайце час выканання і кост токеноў або запытаў праза функцыйнае рэзультат. Відразлівая візуалізацыя костаў з самага пачатку запобегае неспакойным рахункам, калі праця пераходзіць з дэмаверсіі ў спакульнаныя сераўсы.

Як схемы інструментаў увайшлі ў ваш кантэкст

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

{
  "name": "slack_send_message",
  "description": "Send a message to a Slack channel or user",
  "inputSchema": {
    "type": "object",
    "properties": {
      "channel": {
        "type": "string",
        "description": "Channel ID or name to send the message to"
      },
      "text": {
        "type": "string",
        "description": "The message content to send"
      },
      "thread_ts": {
        "type": "string",
        "description": "Optional thread timestamp to reply in a thread"
      }
    },
    "required": ["channel", "text"]
  }
}

Базовы податак, якога нельга ўхіліцца

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

Рэальныя цыфры: тыповы .mcp.json

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

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    },
    "slack": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/projects"]
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"]
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    }
  }
}

Чаму гэта наносіць больш шкоды, чым можа падсказваць сума ў доларах

Для этапы «Чаму гэта болейш» неабяжна ўзначыць вхідныя даны, адпаведальнага за крок і крытэрыя завершэння пры зміне коду. Аперацыйныя працавнікі должны магчымае перайсці на гэты крок з вядомага пункта контролю, не спрабоўваючы здогадвацца пра схованы стан. Конфігурацыю трэба залічыць параду ад коду прыкладнення. Файлы сераўіса, хранільнікі секрэтных даных і флагі функцыйяў должны знаходзіцца ў аднам месцы, якое працавнікі можуць пераглядаць, не чытаючы весь ланцуг задач. Автэнтыфікуйцеся на воратах і паўторна автарызуйцеся на роўні дадзенняў. Толькі токэн-носіцель не ёсць межай арэндаванага рэсурсу.

1. Схемы інструментаў конкуруюць з вашай пераказвой пры аднаковым фіксаваным часовым працэсе.

Для стадзіі канкурэнцыя схемаў 1 адзінкаў неабходна пазначыць вхідныя даны, адпаведальнага за крок і крэтыяры завершэння пры перадзеі коду. Аперацыйныя працавнікі должны магчымае запускаць крок з вядомай точкі контролю, не падозрываючы прыхованы стан. Неабходна аддзёваць як шлях успеху, так і шлях вярнення да нормальнага стану. Перапрыбуткі, людзкія перакрыцця і обработка некорэктных паведамленняў ёсць часткай продукту, а не элементамі пазнейшага дапрацоўвання. Аўтэнтыфікацыя выконваецца на воратах, а паўторная автарызацыя — на роўні дадзенняў. Толькі токэн-носіцель не ёсць межай арэндаванага прыёмніка.

2. Адныя большыя адзінкі паўхваляюць затрымкі і адбуваюцца памылкі у выборэ.

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

3. Запуск сервера стварая затрымку, якая перавышае выкладкі за токены.

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

Як Claude Code ужо скарматывае гэтую проблему

Калі працюеце над раздзелам «Як Claude Code ужо на стадыі», спачатку запісайце умовы працы: неабяжлівыя даны, сігнал успеху і тое, што відбываецца пад частковым невясненнем. Такі спіс контроля дапамагае заліцварыць пазнейшыя змены коду.

The following deferred tools are now available via ToolSearch.
Their schemas are NOT loaded - calling them directly will fail
with InputValidationError. Use ToolSearch with query
"select:<name>[,<name>...]" to load tool schemas before calling them:

mcp__plugin_slack_slack__slack_send_message
mcp__plugin_slack_slack__slack_read_channel
mcp__plugin_github_github__list_recent_viewer_prs
...

Што вы можэце зрабіць па гэтам

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

1. Аўдытуйце кост структуры вашага інструмента

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

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "npx",
  args: ["-y", "@modelcontextprotocol/server-github"],
  env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN! }
});

const client = new Client({ name: "audit", version: "1.0.0" });
await client.connect(transport);

const { tools } = await client.listTools();
console.log(`Server exposes ${tools.length} tools`);

let totalTokens = 0;
for (const tool of tools) {
  const schemaStr = JSON.stringify(tool);
  // ~3-4 chars per token for JSON; this is a rough lower bound
  const estimatedTokens = Math.ceil(schemaStr.length / 3.5);
  totalTokens += estimatedTokens;
  console.log(`  ${tool.name}: ~${estimatedTokens} tokens`);
}
console.log(`\nEstimated context cost: ~${totalTokens} tokens/turn`);
console.log(`(For exact counts, use Anthropic's token counting API)`);

await client.close();

2. Іспользуйце конфігурацыі, прызначаныя для праекта

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

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"]
    }
  }
}

3. Валіце серверы, якія адкрываюць менш, але чыста прызначаныя інструменты

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

4. Адкалкуйце адкладанне загрузкі, калі ствараеце кліент

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

// What goes into the system prompt (cheap, ~5-8 tokens per tool):
const toolDirectory = tools.map(t => t.name);
const systemPrompt = `Available tools (use ToolSearch to load): ${toolDirectory.join(", ")}`;

// What goes into the API request's tools parameter (expensive):
// Only include tools the model has explicitly requested via ToolSearch
const activeTools: ToolSchema[] = [];

// When the model calls ToolSearch("slack_send_message"):
function loadTool(name: string) {
  const schema = cachedSchemas.get(name);
  if (schema) activeTools.push(schema);
}

// API call only pays for activeTools, not all 200
const response = await anthropic.messages.create({
  tools: activeTools,  // 1-4 tools, not 200
  system: systemPrompt,
  messages: conversation,
});

Вывак

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

Чэрніц кантролю

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

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

Автэнтыфікуйцеся на входзе і паўторна автарызуйцеся на роўні дадзенняў. Толькі токэн-носіцель не ёсць межай арэндаванага рэсурсу.

Напісце кароткі посібнік: як зменяць клучы, як спрачыслаць чэргу, як анулюваць пярэдню імпортацыю дадзенняў.

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

Автаналізавайцеся ў шлюзе і паўтарна автаналізавайцеся на роўні дадзенняў. Сам токен-носіцель не ёсць межай арэндавання.

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

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