matematic-mcp-fastmcp-instructions-pl

name	matematic-mcp-fastmcp-instructions-pl
description	Buduj nowy MCP server MateMatic (lub retrofit istniejacego) z 5 elementami zwalidowanymi na dograh v1.31.0 - FastMCP(instructions=) z procedural orchestration, drift test, dwukanalowy auth X-API-Key LUB Bearer, OTel atrybut org_id dla per-tenant routing, ToolAnnotations dla read-only. Uzywaj gdy zaczynasz nowy MCP server (saos/eu-compliance/anonimizacja/pomoc-prawna/kio/isap/inny), retrofit istniejacego do tego patternu, dodajesz nowy tool do MCP, debugujesz dlaczego LLM nie wywoluje Twoich tooli w odpowiedniej kolejnosci, lub gdy klient MCP (Claude Code/Cursor) nie autoryzuje. Trigger - "nowy MCP", "buduj MCP server", "FastMCP", "instructions MCP", "dryft testu MCP", "Claude Code MCP", "auth MCP", "OTel MCP", "FastMCP setup", "retrofit MCP", "tools MCP audit", "tools MCP nie sa wywolywane".
license	Apache-2.0
attribution	{"source":"dograh-hq/dograh","url":"https://github.com/dograh-hq/dograh","license":"BSD-2-Clause","relationship":"pattern-only","note":"Wzorzec źródłowy dla FastMCP(instructions=) i orkiestracji proceduralnej. Treść, testy driftu i kanon MateMatic napisane od zera.\n"}
allowed-tools	["Read","Write","Edit"]
data-residency	local
requires-human-approval	false
pii-egress	none

matematic-mcp-fastmcp-instructions-pl

Wzorzec kanoniczny dla MCP serverow MateMatic. Walidowany empirycznie na dograh-hq/dograh v1.31.0 (production system, 3-4 dni release cycle, 2.6k gwiazdek, drift testy w CI, BSD-2).

Kiedy uzywac

• Nowy MCP server MateMatic od pierwszego commita
• Retrofit istniejacych (saos-orzecznictwo, mcp-eu-compliance, matematic-anonimizacja-pl, mcp-pomoc-prawna-pl, sejm-eli-mcp, mcp-uodo, mcp-kio) - do konca Q3 2026
• Audit istniejacego MCP server (czy ma 5 elementow)
• Debug: LLM nie wywoluje tooli w odpowiedniej kolejnosci, klient MCP nie autoryzuje, error_codes ginace dla LLM

5 elementow kanonu

1. FastMCP(instructions=...) z procedural orchestration

Instrukcje wstrzykiwane do system promptu kazdego klienta MCP. LLM widzi je PRZED pierwszym tool call.

Tresc:

• Call order (ktora kolejnosc wywolywac tools)
• Error handling (jak iteorwac po failed tool call)
• Hard constraints (czego NIE robic)
• Field conventions (kanoniczne nazwy, format ID)
• Style (preferencje przy wyborze toolow gdy wiele rozwiazan)

Anti-content:

• NIE re-enumerowac tool signatures (drift - signatury sa w tools/list)
• NIE re-enumerowac error_codes (drift - error_codes w tool docstring)
• NIE per-field guidance (to lezy w PropertySpec.llm_hint)

Wzor (Python):

from fastmcp import FastMCP
from .instructions import MY_MCP_INSTRUCTIONS
from .tools.foo import foo_tool
from .tools.bar import bar_tool

mcp = FastMCP("matematic-saos", instructions=MY_MCP_INSTRUCTIONS)

for _tool in (foo_tool, bar_tool):
    mcp.tool(_tool)

2. Drift test (tests/test_mcp_instructions_drift.py)

Fail jesli:

• Instructions wymienia tool nie registered
• Tool ma error_code ktorego nie ma w docstring

Wzor w examples/test_instructions_drift.py.

3. Auth dwukanalowy X-API-Key LUB Bearer