Skip to main content
Glama
Dev10x-Guru

ksef-mcp

by Dev10x-Guru
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

ksef-mcp

Lokalny serwer MCP do KSeF (Krajowy System e-Faktur), zbudowany przez Dev10x.Guru.

Uruchamiany na własnej maszynie przez uvx — dane faktur nie przechodzą przez żadną usługę pośredniczącą.

Stan projektu

Wczesny etap. Obecnie repozytorium zawiera wyłącznie szkielet pakietu i jedno narzędzie diagnostyczne (server_info). Narzędzia do wyszukiwania i pobierania faktur nie są jeszcze zaimplementowane — model domenowy jest w trakcie ustalania.

Related MCP server: mcp-facturacion-electronica-es

Wymagania

  • Python 3.13.14 — pin dokładny, nie dolna granica (.python-version oraz requires-python w pyproject.toml). uv pobierze ten interpreter sam, więc nie trzeba instalować go ręcznie.

    Zasada obowiązuje w całym projekcie: przypinamy konkretne wersje, nigdy zakresy — także zależności. Rozjazd interpretera pociąga rozjazd rozwiązanych wersji bibliotek, a uvx i tak rozwiązuje wersję za nas.

  • uv

Instalacja i uruchomienie

Serwer komunikuje się przez stdio i jest uruchamiany przez klienta MCP, nie ręcznie.

Konfiguracja w kliencie MCP (.mcp.json, claude_desktop_config.json):

{
  "mcpServers": {
    "ksef": {
      "command": "uvx",
      "args": ["ksef-mcp"]
    }
  }
}

Aby uruchomić wersję z lokalnego katalogu roboczego zamiast z PyPI:

{
  "mcpServers": {
    "ksef": {
      "command": "uvx",
      "args": ["--from", "/ścieżka/do/ksef-mcp", "ksef-mcp"]
    }
  }
}

Rozwój

make help wypisuje wszystkie dostępne komendy.

make install              # uv sync --group dev
make test                 # uv run pytest z pokryciem
make lint                 # pre-commit na całym drzewie
make upgrade-requirements # uv lock --upgrade
make build-requirements   # eksport do requirements/*.txt

Linting i formatowanie idą wyłącznie przez pre-commit — to ta sama ścieżka, która blokuje commit, więc lokalny przebieg nie rozjeżdża się z hookiem.

Pokrycie testami jest egzekwowane na poziomie 100% (fail_under w pyproject.toml), więc lokalny przebieg i CI stosują identyczny próg.

Bezpieczeństwo danych

Token KSeF nie powinien trafiać do pliku konfiguracyjnego klienta MCP — te pliki są zwykłym tekstem na dysku. Docelowo serwer będzie czytał poświadczenia z keyringu systemowego.

Licencja

AGPL-3.0-only. Pełny tekst w pliku LICENSE.

Available Tools

1 tool
server_infoA

Report the name and version of the running KSeF connector.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
nameYes
versionYes

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are supplied, so the description carries the full disclosure burden; it does indicate the tool is a read-only reporting operation that returns name and version. It does not state whether any authentication or connector state is required, nor does it warn about failure modes. Adequate but thin for an unannotated tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler or repetition. Every word contributes to identifying the tool's output.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no parameters, no annotations, and an output schema that already documents the return shape, the description only needs to identify the operation. It does so clearly; extra detail such as auth or connector-state prerequisites would make it fully complete but is not strictly required here.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there are no parameter semantics to document; the baseline for a parameterless tool applies. The input schema is a bare empty object, consistent with the description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb ('Report') and a precisely scoped resource ('the name and version of the running KSeF connector'). There are no sibling tools to disambiguate against, and the statement leaves no ambiguity about what the call returns.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit when-to-use or when-not-to-use guidance is given, and no alternatives are named (none exist among the siblings). For a zero-argument informational tool the intended use is strongly implied, but nothing is stated outright.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool updatev0.1.0
    • First observedserver_info
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.8/5.0

Scored across 1 tool

Disambiguation5/5

With only a single tool there is no possibility of overlap or misselection; server_info has one clear purpose.

Naming Consistency5/5

The lone tool uses a clean snake_case noun-style name, so no convention conflicts exist within the set.

Tool Count2/5

A KSeF (Polish e-invoicing) connector exposing only a version-reporting tool is far too thin; one trivial tool cannot represent the domain's scope.

Completeness1/5

There are no tools for the core invoicing lifecycle (submitting, fetching, or querying invoices/sessions), leaving the surface severely incomplete for what a KSeF connector implies.

Maintenance

ActivityNo data
ResponsivenessUnresponsive

Resources

Related MCP Connectors

Related MCP Servers

  • mcp-ksef-pl

    cmendezs
    A
    license
    A
    quality
    B
    maintenance
    Model Context Protocol (MCP) server for Polish Electronic Invoicing (KSeF / FA(2)). Provides tools to validate, generate, and explore API specifications for KSeF interoperability.
    10
    3
    Apache 2.0

  • mcp-facturacion-electronica-es

    cmendezs
    A
    license
    A
    quality
    A
    maintenance
    Model Context Protocol (MCP) server for Spanish Electronic Invoicing. Provides tools to generate, validate, and submit invoices across VERI\*FACTU, Facturae/FACe, SII, TicketBAI, and Crea y Crece B2B.
    20
    2
    Apache 2.0

  • @m8t-jacob/mcp-polish-biz

    M8T-Jacob
    A
    license
    A
    quality
    C
    maintenance
    MCP server that provides AI agents with Polish business data tools: identifier validation (NIP, PESEL, REGON, KRS, IBAN), VAT whitelist checks, EU VIES lookups, and NBP exchange rates.
    5
    8 npm
    MIT