Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

mcp-builder

/mcp-builder

Buduje serwer MCP od zakresu API po test z klientem i zestaw ocen, wybierając FastMCP lub SDK TypeScript oraz stdio albo HTTP.

Repozytorium
navin ↗
Licencja
AGPL-3.0
Ostatnia zmiana repozytorium
12.11.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
8
Skrypty
2
Komentarze HTML
0
Adresy URL w SKILL.md
1
Przestarzałość

Brak sygnałów. Repozytorium zmienione 12.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

AGPL-3.0, copyleft: przeróbki udostępniane innym muszą mieć tę samą licencję.

Co sprawdzić przed instalacją
  • 2 skrypty w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.

Skrypty: scripts/connections.py, scripts/evaluate.py

Co robi i kiedy

Buduje serwer MCP od zakresu API po test z klientem i zestaw ocen, wybierając FastMCP lub SDK TypeScript oraz stdio albo HTTP.

Wyzwalacze z opisu

build an MCP serverexpose this API to the agent as toolsevaluate our MCP serverconstruis un serveur MCPexpose cette API à lor
Oryginalny opis (EN)

Build an MCP (Model Context Protocol) server end to end - scope the upstream API, choose Python FastMCP or the TypeScript SDK, design tools an LLM picks correctly (names, schemas, pagination, errors), implement, run over stdio or HTTP, test with a client, write an evaluation set, wire it into Navin. Use when the user asks to "build an MCP server", "expose this API to the agent as tools" or "evaluate our MCP server". In French "construis un serveur MCP", "expose cette API à l'agent comme outils" or "évalue notre serveur MCP".

Jak działa

  1. Workflow
  2. Rules
  3. Bundled files
Sekcje z nagłówków SKILL.md, w oryginale · 167 linii, 1 150 słów
Podgląd SKILL.md
---
name: mcp-builder
description: Build an MCP (Model Context Protocol) server end to end - scope the upstream API, choose Python FastMCP or the TypeScript SDK, design tools an LLM picks correctly (names, schemas, pagination, errors), implement, run over stdio or HTTP, test with a client, write an evaluation set, wire it into Navin. Use when the user asks to "build an MCP server", "expose this API to the agent as tools" or "evaluate our MCP server". In French "construis un serveur MCP", "expose cette API à l'agent comme outils" or "évalue notre serveur MCP".
metadata: {"navin":{"emoji":"🔌","category":"development"}}
---

# MCP Builder

An MCP server turns an API or a local capability into tools, resources and
prompts that any LLM client can call. The server is good when a model with no
other context picks the right tool, fills its arguments correctly and gets back
a result it can use without drowning. Code quality matters; tool design
matters more.

This skill builds the server. Connecting a finished server to Navin (plugin
`mcp.json`, transports, `${VAR}` secrets, `enabledTools`) is the job of the
`mcp-integration` skill; hand over to it at the end.

## Workflow

### 1. Scope

1. Ask what the server must let the agent do, in task terms ("find overdue
   invoices and send reminders"), not endpoint terms. Record the three to five
   tasks that matter.
2. Read the upstream API: authentication, rate limits, pagination style, the
   data shapes of the objects involved. Use `web_fetch` on the official docs;
   read local code with `read_file` when the "API" is an internal module.
3. List candidate tools. Prefer broad coverage of read operations plus the
   few write operations the tasks need. Add a workflow tool (one call that
   chains several API calls) only when the agent would otherwise repeat the
   same five-call sequence.
4. Decide the transport: stdio for a local, single-user server that Navin
   starts itself; streamable HTTP for a remote or shared server. Avoid SSE
   for new servers.
5. Confirm the plan with the user when scope is ambiguous (`ask_user` with
   two or three concrete tool sets).

### 2. Choose the stack

| Pick | When |
|---|---|
| Python + FastMCP (`mcp` package) | the team writes Python, the server wraps Python code or data science libs, fastest to iterate |
| TypeScript + official SDK | the server ships with `npx`, runs inside a Node toolchain, or must be installed by non-Python users |

Walkthroughs with a complete small server for each: `references/python-server.md`
and `references/typescript-server.md`. Read `references/mcp-best-practices.md`
before designing the first tool.

### 3. Design the tools

For each tool, write the contract before the code:

- Name: `<service>_<verb>_<object>` in snake_case (`notes_search`,
  `notes_create`). The prefix avoids collisions with other servers.
- Description: two to four sentences for the model, not for a human reader:
  what it does, what it returns, when to use a sibling tool instead, one
  example request. This text is the whole documentation the model sees.
- Input schema: typed fields with constraints and a description per field;
  defaults for optional fields; `limit` and `offset` (or a cursor) on anything
  that lists.
- Output: readable text by default, structured JSON on request
  (`response_format`), paginated with `has_more` and `next_offset`, capped at
  roughly 25,000 characters by returning fewer items, never by truncating.
- Errors: returned as tool errors (`isError`) with a sentence that says how to
  recover ("unknown folder; call notes_list_folders first"). Never a stack
  trace.
- Annotations: `readOnlyHint`, `destructiveHint`, `idempotentHint`,
  `openWorldHint` set honestly.

### 4. Implement

1. Scaffold the project as the chosen walkthrough shows (`pyproject.toml` or
   `package.json`, one module per domain, a shared API client, one error
   formatter).
2. Write the shared pieces first: API client with auth from environment
   variables, error mapping, pagination helper, response renderer.
3. Add tools one by one, each with its schema, description and annotations.
   Keep logging on stderr: stdout belongs to the protocol when running over
   stdio.
4. Add resources for data the model should read as context (configuration,
   schemas) and prompts for repeatable instructions, only when they earn
   their place.
5. Compile or type-check: `python3 -m py_compile server.py` or `npm run build`.

### 5. Run and test with a client

1. Start the server in a background `exec` session (stdio servers wait
   silently on stdin; HTTP servers print their port on stderr).
2. List the tools through the bundled client:

   ```bash
   python3 navin/skills/mcp-builder/scripts/connections.py list-tools \
     --transport stdio --command python3 --arg server.py
   python3 navin/skills/mcp-builder/scripts/connections.py call \
     --transport http --url http://127.0.0.1:8000/mcp \
     --tool notes_search --args '{"query": "budget", "limit": 5}'
   ```

   The script needs the `mcp` Python package; it prints an install hint when
   the package is missing.
3. Read the listed schemas as the model would: is every tool distinguishable
   from its siblings by description alone? Are required fields obvious?
4. Call each tool with valid, missing and wrong arguments. Check the error
   text tells the caller what to do next. Check a large listing stays under
   the size cap and reports `has_more`.
5. For HTTP servers, also check the endpoint answers with the auth header and
   rejects without it.

### 6. Write the evaluation set

The measure of the server is whether a model with only these tools answers
realistic questions. Follow `references/evaluation.md`: 10 or more questions,
read-only, independent, multi-step, each with one verifiable answer.

```bash
python3 navin/skills/mcp-builder/scripts/evaluate.py --validate-only evaluation.json
python3 navin/skills/mcp-builder/scripts/evaluate.py evaluation.json \
  --transport stdio --command python3 --arg server.py --output eval-report.md
```

`scripts/evaluation.example.json` shows the format (JSON; the XML form with
`<qa_pair>` elements is accepted too). The script validates the file, lists
the server tools and writes a report skeleton; it does not call an LLM. Run
each question through the agent itself (or a `spawn` subagent given only the
tool list and the question), fill in actual answers and verdicts, then fix the
tools that caused wrong turns and run again.

### 7. Wire into Navin

Switch to the `mcp-integration` skill: write the plugin `mcp.json` (stdio
`command`/`args` behind `${NAVIN_PLUGIN_ROOT}`, or `streamableHttp` `url` with
`${TOKEN}` headers), restrict with `enabledTools` if the server exposes more
than the plugin needs, enable the plugin and confirm the `mcp_<server>_<tool>`
names appear. Document the required environment variables in the plugin
README.

## Rules

- Descriptions are for the model: say what, what it returns, when not to use
  it. No marketing, no internal jargon.
- One concept per tool. A tool with a `mode` argument that changes what it
  does is two tools.
- Never load an entire dataset to answer a page; pass `limit` and `offset`
  to the upstream API.
- Secrets come from environment variables, validated at startup with a
  clear message when missing. Never in code, never echoed in errors.
- Validate every input (pydantic or zod) and every path or URL that reaches
  the operating system or the network.
- Bind local HTTP servers to `127.0.0.1` and check the `Origin` header.
- Keep the server name stable and general (`notes_mcp`, `notes-mcp-server`):
  Navin derives tool names from it.

## Bundled files

- `references/mcp-best-practices.md` - naming, descriptions, schemas,
  response size, pagination, errors, annotations, auth, transports, security.
- `references/python-server.md` - FastMCP walkthrough: complete example
  server, lifespan, pydantic inputs, resources, prompts, stdio and HTTP,
  `pyproject.toml`.
- `references/typescript-server.md` - official TypeScript SDK walkthrough:
  complete example, zod schemas, stdio and HTTP transports, `package.json`,
  build.
- `references/evaluation.md` - how to write the questions, grading rubric,
  iteration loop.
- `scripts/connections.py` - stdio, streamable HTTP and SSE client: list
  tools, call a tool, print JSON.
- `scripts/evaluate.py` - validate an evaluation file, list tools, write the
  report skeleton.
- `scripts/evaluation.example.json` - eleven example questions for a notes
  server.
Pliki w paczce (8)
  • SKILL.md 8 KB
  • references/evaluation.md 5 KB
  • references/mcp-best-practices.md 6 KB
  • references/python-server.md 11 KB
  • references/typescript-server.md 11 KB
  • scripts/connections.py 9 KB
  • scripts/evaluate.py 10 KB
  • scripts/evaluation.example.json 3 KB

Wersje

RepozytoriumWynikLicencja
Ta strona · Navinspire-ia/navin100AGPL-3.0
Kanevry/session-orchestrator100MIT
DroBov1Tya/dusk_code100MIT
thevibeworks/claude-code-docs100MIT
drvoss/everything-copilot-cli100MIT
event4u-app/agent-config100MIT
akillness/jeo-skills100MIT
davila7/claude-code-templates100MIT
shareai-lab/learn-claude-code100MIT

Migawka bazy z 13.11.2026 · wersja paczki 7ce6d844c52d (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100mcp-server-scaffold
    Prowadzi przy budowie serwera MCP łączącego usługi firmowe z Claude, w Javie (MCP Java SDK, Spring AI) lub Pythonie (FastMCP).
  • 100fai-mcp-python-generator
    Tworzy szkielet gotowego do produkcji serwera MCP w Pythonie: dekoratory FastMCP, asynchroniczne narzędzia, ustrukturyzowane wyjścia, integracja z Azure oraz transport stdio lub HTTP.
  • 100mcp-server
    Tworzy szkielet i przegląda serwery MCP w Pythonie (FastMCP) lub TypeScript, z opisanymi narzędziami, walidacją wejścia i obsługą błędów.
  • 100mcp-server
    Projektuje i buduje własne serwery MCP: narzędzia, transport i uwierzytelnianie, nazewnictwo, schematy i błędy oraz publikację konfiguracji.
  • 100fastmcp
    Buduje serwery i klientów Model Context Protocol w Pythonie z FastMCP: funkcja z dekoratorem staje się narzędziem, zasobem lub promptem dla agenta AI.
  • 100mcp-server-building-python-sdk
    Buduje asynchroniczne serwery MCP w Pythonie z oficjalnym pakietem mcp lub FastMCP.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.