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

build-mcp-server

/build-mcp-server

Planuje, buduje i testuje serwer MCP, którego narzędzia agent wybiera poprawnie, z czytelnymi nazwami i zrozumiałymi błędami.

Repozytorium
yaap ↗
Licencja
MIT
Ostatnia zmiana repozytorium
13.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
2
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

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

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Planuje, buduje i testuje serwer MCP, którego narzędzia agent wybiera poprawnie, z czytelnymi nazwami i zrozumiałymi błędami.

Oryginalny opis (EN)

Plan, build, test and evaluate an MCP server whose tools an agent picks and uses correctly, with clear names and descriptions, typed inputs, concise paginated results and helpful errors. Use it when you build an MCP server, wrap an API as agent tools, or an agent misuses a tool.

Jak działa

  1. 1. Research
  2. 2. Design the tools
  3. 3. Errors that teach
  4. 4. Build
  5. 5. Test
  6. 6. Evaluate
  7. Report
Sekcje z nagłówków SKILL.md, w oryginale · 116 linii, 1 019 słów
Podgląd SKILL.md
---
name: build-mcp-server
description: Plan, build, test and evaluate an MCP server whose tools an agent picks and uses correctly, with clear
  names and descriptions, typed inputs, concise paginated results and helpful errors. Use it when you build an MCP
  server, wrap an API as agent tools, or an agent misuses a tool.
license: Apache-2.0
metadata:
  sources: anthropic-skills/skills/mcp-builder, agency-agents/specialized/specialized-mcp-builder.md
---

# Build an MCP server

An MCP server is judged by one thing: can an agent use it to finish real tasks? The agent only sees tool names,
descriptions, input schemas and results. Treat those as the user interface, design them before the code, and test
them with an agent, not only with unit tests.

## 1. Research

- **The tasks.** Write five to ten things a user will ask an agent to do with this service ("which open issues have
  no owner?", "move this card to Done"). They drive every later choice.
- **The API.** Read the service's documentation with `web_fetch`: authentication, the main resources, pagination,
  rate limits, error format.
- **The protocol and the SDK.** SDKs change between major versions. Before writing code, fetch the current README of
  the official SDK for your language and follow its patterns, not ones from memory. Use stdio for a server that runs
  on the user's machine, Streamable HTTP for a remote one.

## 2. Design the tools

Write the tool list as a table before any code: name, one-line purpose, inputs, result, read-only or not.

- **Coverage first, then shortcuts.** Cover the common operations of the API so the agent can combine them. Add a
  workflow tool (several calls in one) only for a task that is frequent and awkward to compose.
- **Names the agent can choose from.** A service prefix and a verb: `tracker_search_issues`, `tracker_get_issue`,
  `tracker_update_issue`. One job per tool; a `mode` parameter that switches behaviour is two tools in disguise.
- **Descriptions say when to use it.** What it does, when to choose it over its neighbours, and what it returns. "Use
  `tracker_search_issues` first when you only know words from the title."
- **Typed inputs with limits.** Every parameter has a type, a description, constraints (ranges, patterns, enums) and
  a default where one makes sense. Validate with the SDK's schema support (Pydantic in Python, a schema library in
  TypeScript).
- **Concise results.** Return the fields an agent needs, not the raw API response. Offer a detail level or a choice
  of format (short Markdown for reading, JSON for further processing) when both are useful. Return structured content
  next to the text when the SDK supports it.
- **Pagination always.** A `limit` with a sensible default (20 to 50), a cursor or offset, and in the result
  `has_more` and the next cursor. Never load a whole collection into one result.
- **Annotations.** Mark each tool read-only, destructive, idempotent or open-world. Clients use them to decide what
  to ask the user about; they are hints, not security.

## 3. Errors that teach

An error result says what went wrong and what to try next, in the agent's terms: "No issue 4512. Search with
`tracker_search_issues` to find its number." Return it as a tool error result; never crash the server or return an
empty success. Translate API errors (401, 404, 429) into such messages, and include the wait time for a rate limit.

## 4. Build

- Keep the structure small: an API client with authentication, one module per group of tools, shared helpers for
  errors, formatting and pagination. No duplicated request code.
- Secrets come from environment variables, never from code or tool arguments, and never appear in results or logs.
- A stdio server writes logs to stderr only; anything on stdout corrupts the protocol.
- A local HTTP server binds to `127.0.0.1` and checks the `Origin` header, against DNS rebinding. A remote one
  requires authentication on every request.
- Use the token with the least rights the tools need; a read-only server gets a read-only token.
- Use async I/O for network calls, with a timeout on each.

A minimal Python tool, to show the shape (check the SDK's current API before copying the pattern):

```python
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("tracker")

ISSUES = {4511: {"title": "Login fails after password reset", "state": "open"}}


@mcp.tool()
def tracker_get_issue(issue_id: int) -> dict[str, str]:
    """Get one issue by its number. Use tracker_search_issues first when you only know words from its title."""
    issue = ISSUES.get(issue_id)
    if issue is None:
        raise ValueError(f"No issue {issue_id}. Search with tracker_search_issues to find its number.")
    return issue


if __name__ == "__main__":
    mcp.run()
```

## 5. Test

- **Unit tests** for each tool function: valid input, invalid input, an empty result, an API error, a second page.
  Fake the API at the HTTP edge (the `python-testing` skill).
- **The type checker and linter** on the whole server.
- **In YAAP.** Add the server under Project settings, *MCP servers* (stdio with its command, or its URL), and use its
  test: it lists the tools YAAP sees. Then ask an agent in a conversation to do the tasks from step 1, and read its
  tool calls in the trace. A tool the agent skips or misuses needs a better name or description, not a longer prompt.
  With more than five tools, check that `find_tools` finds the right one from a plain query.

## 6. Evaluate

Write about ten evaluation questions that only the server's tools can answer:

- **realistic:** something a user would really ask;
- **demanding:** each needs several tool calls, such as a search, a detail and a comparison;
- **read-only:** answering changes nothing;
- **independent:** no question depends on another;
- **verifiable and stable:** one short answer that can be compared as text and will not change next week.

Solve each one yourself with the tools to confirm the answer. Save them as the project's eval cases, so `/eval` runs
them after each change to the tools and shows whether a new description helped or hurt.

## Report

```
Tasks: <the user tasks the server supports>
Tools: <name - purpose - read-only or not>
Transport and auth: <stdio or HTTP, where the secret comes from>
Tests: <command and result>
Agent check: <tasks tried in YAAP, tools that were misused and what changed>
Evaluation: <number of questions, how many answered correctly>
```

Adapted from the `mcp-builder` skill of anthropics/skills under Apache-2.0: only its Markdown guidance, rewritten and
shortened, without its scripts, reference code or vendor-specific steps, and with YAAP's MCP server settings, trace
and eval cases added.
Pliki w paczce (2)
  • LICENSE.txt 11 KB
  • SKILL.md 7 KB

Wersje

RepozytoriumWynikLicencja
Ta strona · jelvodev/yaap100MIT
anthropics/claude-plugins-official100Apache-2.0
velimirmueller/ai-development-skills100MIT
tufflerp/Prabh-s-CSC100MIT
HK-hub/AgentSkills100MIT
pproenca/dot-skills100MIT

Migawka bazy z 13.11.2026 · wersja paczki eb84e7f6e770 (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

  • 100eval-mcp
    Mierzy, czy Claude poprawnie używa narzędzi serwera MCP: dokładność wyboru narzędzia, jakość schematów i iteracyjna optymalizacja opisów.
  • 90mcp-tool-design
    Projektuje narzędzia MCP, które agent wybiera poprawnie, dzięki nazwom, opisom i schematom wskazującym właściwe wywołanie i uniemożliwiającym błędne.
  • 86diagnosing-mcp
    Diagnozuje serwer MCP, który nie łączy się, nie pokazuje narzędzi albo którego narzędzia zawodzą.
  • 100mcp-server-builder
    Buduje, podłącza i debuguje serwer MCP dający Claude dostęp do wewnętrznego API, bazy danych lub narzędzia SaaS, także gdy narzędzia serwera się nie pojawiają.
  • 100build-mcp
    Buduje serwer MCP od początku do końca, dopasowany do odbiorcy: najpierw pyta, dla kogo jest i co opakowuje, a potem prowadzi przez analizę, budowę, wdrożenie, skalowanie i dystrybucję.
  • 100mcp-build
    Projektuje, buduje i testuje serwery MCP, które dają agentowi nazwane, typowane i ograniczone narzędzia zamiast powłoki.

Uwagi i zgłoszenia

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