Build Your First MCP

Here's a real read-only tool from the kit — it answers "do you have X, and how many?" by reading one JSON file. It returns plain data; it never writes or sends anything.

// search_inventory — find products by name, SKU, or category.
// The AI reads this description to decide when to call it.
export async function searchInventory({ query = "", inStockOnly = false }) {
  const data = await loadData();        // your shop.json
  let results = data.inventory;
  if (query) results = results.filter(i =>
    (i.name + i.sku + i.category).toLowerCase().includes(query.toLowerCase()));
  if (inStockOnly) results = results.filter(i => i.in_stock > 0);
  return { count: results.length, items: results };  // just reads
}

Two more ship with the kit — read_pricelist and get_hours — written the same way. Three tools, one data file. That's a complete MCP server.

With the kit downloaded:

# 1. set up (writes .env — Claude key is optional)
npm install
npm run setup

# 2. prove it works with NO key and NO network beyond localhost
npm run dryrun

# 3. let Claude drive the tools
npm start                # server on http://127.0.0.1:8765/mcp — leave running
npm run agent -- "Do you sell painter's tape, and is it in stock?"

Prefer the Claude desktop app over the CLI? Run npm start and add the server at http://127.0.0.1:8765/mcp (Streamable HTTP) as a connector — Claude lists the same three tools and calls them in chat.

1. Copy data/shop.sample.json to data/my-shop.json.
2. Replace its contents with your hours, inventory, and prices (same shape).
3. Run npm run setup again and give it the new path (or set DATA_FILE in .env).
4. Run npm run dryrun — same tools, now answering about your business.

The file lives on your machine and is yours to own and edit. The kit never invents data it can't read from that file.

Before you wire any AI into real tools, run the 5 questions from Lesson 1's safety panel against every tool:

1. What can it touch? Scope each tool to one narrow action.
2. Can it spend money? If yes — it drafts only; a human approves.
3. Can it be undone? Prefer reversible actions; log everything.
4. Who sees the result? Show the plan before it happens, not after.
5. What if it's wrong? A draft that's wrong costs nothing. Ship drafts.

The kit's src/server.js carries a commented "ADDING A WRITE TOOL SAFELY" section. You copy it in deliberately, when you understand it — it is not enabled by default.