Skip to content

ericrisco/rsc-harness / skills/building-agents

building-agents

Unverified

Use when building or restructuring an LLM agent — provider adapter, tool calling, structured output, RAG, agent loop, eval gate, cost routing, tracing, MCP server — model-agnostic across OpenAI/Anthropic/Gemini/OSS so a model swap is a config change. NOT vector-store SQL alone (that is `postgresdb`) or service deployment (that is `deployment`).

FileKindSize
SKILL.mdskill md19.4 KB
evals/README.mdmarkdown2.9 KB
evals/cases.yamlconfig6.3 KB
references/agent-loops-and-harness.mdmarkdown14.4 KB
references/evals-and-observability.mdmarkdown15.6 KB
references/mcp-servers.mdmarkdown11.6 KB
references/provider-abstraction.mdmarkdown20.8 KB
references/tools-and-rag.mdmarkdown15.6 KB
scripts/verify.shexecutablescript4.6 KB

references/mcp-servers.md

View on GitHub
# MCP servers — decide, build, secure

The Model Context Protocol lets an MCP **client** (Claude Desktop/Code, Cursor, your own
agent) discover and call tools, read resources, and use prompts hosted by an MCP
**server**. Build one only when reuse across clients justifies the cost; otherwise native
in-process tools (see `tools-and-rag.md`) are simpler and cheaper. Versions and signatures
move — confirm against the current SDK docs before shipping.

## MCP vs native tools

| Situation | Choose |
|---|---|
| Tools live in the same process/repo as the agent | **Native tools** — direct function calls, no transport, no extra schema tokens |
| One agent, one deployment, no external consumers | **Native tools** |
| Tools must be reused by multiple clients / teams | **MCP** |
| Tools run out-of-process or need their own deploy lifecycle | **MCP** |
| You want a third-party client (Claude Desktop, Cursor) to use your tools | **MCP** |
| Tools wrap a system with its own auth/network boundary | **MCP** |

MCP is not free: every tool's schema is re-sent to the model (token cost — ties to
context-budget), there's a transport hop (latency), and you now operate a server
(deploy, auth, monitoring). Pay that only for genuine cross-client reuse.

## Concepts

- **Tools** — actions the model invokes (search, mutate, compute). Side-effecting; validate
  inputs, return structured results.
- **Resources** — read-only data the client fetches by URI (`config://app`,
  `file:///logs/today`). No side effects.
- **Prompts** — parameterized prompt templates the client can surface to users.

Lifecycle: client connects over a transport → negotiates capabilities → lists
tools/resources/prompts → calls them on demand. Note (spec `2025-11-25`; stateless-core RC
`2026-07-28`; verify before quoting): the RC makes the protocol core **stateless**, adding
Extensions, Tasks, and MCP Apps — design servers to avoid per-connection state so they
forward-port cleanly and scale horizontally.

## Python server (FastMCP)

FastMCP gives you decorators that register tools/resources/prompts; Pydantic types on the
signature become the input schema automatically. Two packages expose a `FastMCP` class:
the standalone **`fastmcp`** 2.x (actively developed, install `pip install fastmcp`,
import `from fastmcp import FastMCP`) and the frozen 1.x snapshot bundled in the official
`mcp` SDK (`from mcp.server.fastmcp import FastMCP`). Use the standalone package — its
in-process `Client` (see Testing below) makes the round-trip test trivial. Pick one and
keep imports consistent across server and tests.

```python
# server.py — run with: python server.py   (stdio transport)
from __future__ import annotations

from typing import Literal

from fastmcp import FastMCP
from pydantic import BaseModel, Field

mcp = FastMCP("invoices")

# In-memory stand-in for a real store; replace with a DB session in production.
_INVOICES: dict[str, dict] = {}


class CreateInvoice(BaseModel):
    customer_id: str = Field(min_length=1, description="Customer id, e.g. 'cus_42'.")
    amount_cents: int = Field(gt=0, le=10_000_000, description="Amount in cents (> 0).")
    currency: Literal["EUR", "USD"] = "EUR"


@mcp.tool()
def create_invoice(args: CreateInvoice) -> dict:
    """Create an invoice. Returns the new invoice id and status."""
    inv_id = f"inv_{args.customer_id}_{len(_INVOICES) + 1}"
    _INVOICES[inv_id] = {"customer_id": args.customer_id, "amount_cents": args.amount_cents,
                         "currency": args.currency, "status": "open"}
    return {"id": inv_id, "status": "open"}


@mcp.resource("invoice://{invoice_id}")
def read_invoice(invoice_id: str) -> str:
    """Read-only lookup of an invoice by id."""
    inv = _INVOICES.get(invoice_id)
    if inv is None:
        raise ValueError(f"unknown invoice: {invoice_id}")   # surfaced as a structured error
    return f"Invoice {invoice_id}: {inv['amount_cents']} {inv['currency']} ({inv['status']})"


@mcp.prompt()
def dunning_email(invoice_id: str) -> str:
    """Template a polite payment-reminder email for an overdue invoice."""
    return (f"Write a concise, friendly reminder that invoice {invoice_id} is overdue. "
            f"Offer a payment link and a contact for questions.")


if __name__ == "__main__":
    mcp.run()  # stdio; for HTTP use mcp.run(transport="streamable-http")
```

## TypeScript server

The repo runs Next.js, so the TS SDK matters. The current registration API is
`registerTool(name, { description, inputSchema }, handler)` with **Zod** schemas
(`inputSchema` must be a `z.object(...)`). Imports below use the stable
`@modelcontextprotocol/sdk` subpath form; the v2 split packages
(`@modelcontextprotocol/server`, `@modelcontextprotocol/node`) expose the same API under
new paths — verify against the SDK version in your `package.json`.

```typescript
// server.ts — install: npm i @modelcontextprotocol/sdk zod
import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import { randomUUID } from "node:crypto";
import { z } from "zod";

const invoices = new Map<string, { amountCents: number; currency: string; status: string }>();

export function buildServer(): McpServer {
  const server = new McpServer({ name: "invoices", version: "1.0.0" });

  server.registerTool(
    "create_invoice",
    {
      title: "Create invoice",
      description: "Create an invoice. Returns the new invoice id and status.",
      inputSchema: z.object({
        customerId: z.string().min(1).describe("Customer id, e.g. 'cus_42'."),
        amountCents: z.number().int().positive().max(10_000_000).describe("Amount in cents (> 0)."),
        currency: z.enum(["EUR", "USD"]).default("EUR"),
      }),
    },
    async ({ customerId, amountCents, currency }) => {
      const id = `inv_${customerId}_${invoices.size + 1}`;
      invoices.set(id, { amountCents, currency, status: "open" });
      return { content: [{ type: "text", text: JSON.stringify({ id, status: "open" }) }] };
    },
  );

  // A templated URI must be wrapped in ResourceTemplate so {invoiceId} is parsed and
  // bound; { list: undefined } means clients can't enumerate every invoice, only fetch
  // one by id. A bare "invoice://{invoiceId}" string would NOT bind the param.
  server.registerResource(
    "invoice",
    new ResourceTemplate("invoice://{invoiceId}", { list: undefined }),
    { description: "Read-only invoice lookup by id." },
    async (uri, { invoiceId }) => {
      const id = String(invoiceId);
      const inv = invoices.get(id);
      if (!inv) throw new Error(`unknown invoice: ${id}`);
      return { contents: [{ uri: uri.href, text: `Invoice ${id}: ${inv.amountCents} ${inv.currency}` }] };
    },
  );

  return server;
}

// stdio entrypoint (local clients: Claude Desktop/Code)
async function mainStdio(): Promise<void> {
  const server = buildServer();
  await server.connect(new StdioServerTransport());
}

// Streamable HTTP entrypoint (remote clients) — one stateless transport per request
import express from "express";

export function httpApp() {
  const app = express();
  app.use(express.json());
  app.post("/mcp", async (req, res) => {
    const server = buildServer();
    const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: () => randomUUID() });
    await server.connect(transport);
    await transport.handleRequest(req, res, req.body);
  });
  return app;
}

if (process.argv[2] === "stdio") {
  mainStdio().catch((e) => {
    console.error(e);
    process.exit(1);
  });
}
```

## Transports

- **stdio** — the server is a subprocess of a local client (Claude Desktop/Code). Simplest;
  no network surface; one client per process. Use for local dev tools and desktop
  integrations.
- **Streamable HTTP** — a single MCP HTTP endpoint for remote clients (Cursor, cloud,
  your own agent service). Scales horizontally; this is the direction the stateless-core RC
  pushes. Use for shared/team servers.
- **SSE** — legacy only; support it solely for backward compatibility with old clients.

Capability discovery: the RC formalizes a `.well-known` advertisement so clients can find a
server's capabilities without a manual config — prefer it once your client supports it.

## Security

An MCP server is an attack surface; the model drives its inputs.

- **Auth on HTTP transport** — require OAuth or a bearer token; reject unauthenticated
  requests at the edge. stdio inherits the local user's trust; HTTP does not.
- **Input validation** — every tool validates with Pydantic/Zod before acting (the examples
  above do). Never trust model-supplied ids, paths, or SQL.
- **No raw stack traces to the model** — return a structured error message; a traceback leaks
  internals and wastes context.
- **Rate limiting** — per-client limits on tool calls; expensive tools get their own cap.
- **Egress controls** — allowlist the hosts/commands a tool may reach (see sandboxing in
  `tools-and-rag.md`).
- **Tool allowlisting** — expose only the tools a given client needs; don't ship one server
  with every capability.
- **Confused-deputy risk** — the server acts with its *own* credentials on behalf of a
  model that may be steered by untrusted input. Use **least-privilege tokens** scoped to
  exactly what each tool needs, and require human approval for high-risk actions.

```typescript
// Bearer-token gate for the HTTP transport (add before transport.handleRequest)
app.use("/mcp", (req, res, next) => {
  const token = req.header("authorization")?.replace("Bearer ", "");
  if (token !== process.env.MCP_TOKEN) {
    res.status(401).json({ error: "unauthorized" });
    return;
  }
  next();
});
```

## Testing & debugging

- **MCP Inspector** — the official interactive client for poking a server during
  development: `npx @modelcontextprotocol/inspector python server.py`. Lists tools/resources
  and lets you call them by hand.
- **Contract test** — automate the round-trip: connect, list tools, call one, assert the
  shape. Run it in CI.

```python
# test_server.py — pytest + the in-process FastMCP client
import pytest
from fastmcp import Client

from server import mcp  # the FastMCP instance


@pytest.mark.anyio
async def test_create_and_read_round_trip():
    # Pass the server instance straight to Client -> in-memory transport, no subprocess.
    async with Client(mcp) as client:
        tools = await client.list_tools()
        assert "create_invoice" in {t.name for t in tools}

        created = await client.call_tool("create_invoice",
            {"args": {"customer_id": "cus_42", "amount_cents": 500, "currency": "EUR"}})
        inv_id = created.structured_content["id"]

        # idempotency / read-back: the resource reflects the created invoice
        res = await client.read_resource(f"invoice://{inv_id}")
        assert "500 EUR" in res[0].text
```

## Packaging

Pin the SDK and the spec version you target so upgrades are deliberate:

```json
{
  "name": "invoices-mcp",
  "version": "1.0.0",
  "mcp": { "specVersion": "2025-11-25" },
  "dependencies": {
    "@modelcontextprotocol/sdk": "1.x",
    "zod": "3.x"
  }
}
```

Client-registration snippet (Claude Desktop/Code `mcpServers` config) for the stdio server:

```json
{
  "mcpServers": {
    "invoices": {
      "command": "python",
      "args": ["/abs/path/to/server.py"],
      "env": { "DATABASE_URL": "postgresql+asyncpg://app:secret@db/app" }
    }
  }
}
```

## See also

- `tools-and-rag.md` — native tools, Pydantic/Zod validation, and sandboxing the server reuses.
- `provider-abstraction.md` — when the agent calling this MCP server stays provider-agnostic.
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall