convez.ai
MCP ServerDevOps & InfraestruturaIntermediário
cejor6

MCPConform

cejor6/mcpconform

Valida setup MCP offline com suporte multi-provider e GitHub Actions

Ver no GitHub
BomPluginScore · de 0 a 100

Linter estático agnóstico para validar definições de ferramentas MCP, manifests server.json e configs de cliente. Verifica portabilidade e conformidade com especificação MCP 2025-11-25, oferecendo suporte multi-provider (Anthropic, OpenAI) e saída em SARIF para integração CI/CD.

Instalação

$npx convez-ai cejor6/mcpconform

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
1
Saúde
85%
Último commit
há 1 semana
Versão
v0.2.1
Issues abertas
6
Contribuidores
2

Casos de uso

  • Validar portabilidade de definições MCP entre provedores
  • Integrar linting MCP em pipelines CI/CD com SARIF reporting
  • Inspecionar servidores MCP ao vivo e capturar dumps para auditoria offline

Veredito

Ferramenta essencial para quem trabalha com MCP em produção. Preenche um gap real: validação estática offline de artefatos MCP com rigor comparável a shellcheck/hadolint, sem depender de runtime ou testes ao vivo.

README

A tradução para o português deste README ainda está na fila.

mcpconform

A static linter for MCP setup correctness: tool definitions, the server.json registry manifest, and client config files (.mcp.json / claude_desktop_config.json / mcpServers). Think shellcheck/hadolint, but for the Model Context Protocol — and provider-agnostic by design.

It checks, statically and offline, that your MCP setup is correct and portable. It is intentionally not a security scanner and not a live conformance tester — it validates the shape and portability of your tool surface, the part nothing else checks.

Spec baseline: MCP 2025-11-25.

Install

# one-off, no install
npx mcpconform path/to/server.json .mcp.json tools.json --target anthropic,openai

# or install the CLI
npm install -g mcpconform
mcpconform tools.json --target anthropic,openai

Requires Node ≥ 20.

Usage

Point it at any MCP artifact — tool-definition dumps, server.json, or client config. The type is auto-detected by shape (override with --type), and you can pass several at once:

mcpconform server.json .mcp.json tools.json --target anthropic,openai
  • --target a,b — provider profiles to check against. Empty = pure MCP-spec checks.
  • --portable — must satisfy the strictest common denominator of every major provider.
  • --mode strict — also apply each provider's strict-mode constraints.
  • --format sarif --out file.sarif — emit SARIF for GitHub code scanning.
  • --min-severity error|warn|info — report only findings at or above this tier. This is a display filter, not a fail-gate: the exit code is unaffected — only error-tier findings ever fail a run. Also settable as minSeverity in config. Handy in CI to drop info-tier noise without per-rule off suppressions.
  • --expand — a few info rules flag framework-injected noise that repeats identically on every tool (e.g. FastMCP stamping a non-reverse-DNS _meta key on all of them). By default, when such a finding hits 3+ tools it collapses to a single line with a count — in the human report and in SARIF (one alert instead of N identical ones). --expand (or expand in config) lists every occurrence. Collapsing is display-only (never changes the exit code) and opt-in per rule (aggregate: true in rules.json): warn/error and per-tool-actionable info findings always stay itemized with their tool names.

Lint a live server (any language)

When you can't get a static dump, inspect launches or connects to the server and pulls tools/list over the MCP stdio handshake — exactly what a client does — then lints it:

mcpconform inspect --target anthropic,openai -- python server.py

Servers that need env vars to start inherit your shell env, or pass --env-file .env / --env KEY=VAL. Tool listing rarely makes network calls, so placeholder values are usually enough. To avoid secrets in CI, capture a reusable dump once and commit it:

mcpconform inspect --dump tools.json -- <cmd>

In CI, add --min-tools <n> so a server that boots but registers too few tools fails the run (exit 2) instead of passing green having linted nothing — a broken tool import would otherwise go unnoticed:

mcpconform inspect --min-tools 1 -- <cmd>

GitHub Action

Lint on every push and upload findings to the Security tab as SARIF:

- uses: cejor6/mcpconform@v1
  id: mcpconform
  with:
    files: server.json .mcp.json
    targets: anthropic,openai
- uses: github/codeql-action/upload-sarif@v4
  with:
    sarif_file: ${{ steps.mcpconform.outputs.sarif }}

Provider-agnostic architecture

The engine knows nothing about any specific LLM vendor. Every consumer of a tool definition — an LLM tool-use API or an MCP host — is described by a declarative profile (profiles/*.json, validated by profiles/profile.schema.json).

  • Core rules (tool/*, server-json/*, client-config/*) are pure MCP-spec / JSON-Schema / registry correctness. They name no vendor and run by default.
  • provider/* rules are a single parameterized family. They read whatever profile(s) you target and report which profile a finding violated. Adding a new provider is a data change (drop a JSON file), never a code change.
--target (none)                      -> pure MCP spec (default, fully agnostic)
--target anthropic                   -> one consumer
--target anthropic,openai            -> portable: tool must satisfy BOTH
--portable                           -> survives every major provider

Shipped profiles

idkindverifiedname rulenotable
anthropicllm-provider✅^[a-zA-Z0-9_-]{1,64}$strict mode drops min/max/length + recursion
openaillm-provider✅^[a-zA-Z0-9_-]{1,64}$description ≤1024; strict = addlProps:false + all-required, depth ≤5
geminillm-provider✅^[a-zA-Z_][a-zA-Z0-9_.-]{0,63}$OpenAPI-3.0 subset (allowlist); no anyOf/$ref baseline
mistralllm-provider⛔ stub—demonstrates the extension pattern
generic-strictsynthetic✅^[a-zA-Z_][a-zA-Z0-9_-]{0,63}$strictest common denominator (--portable)

verified: true means every constraint was read from that consumer's own docs (cited in source). Findings from a verified: false profile are flagged by meta/profile-unverified, so a guessed number never reads as fact.

The flagship divergence this catches

A name like admin.tools.list is legal per the MCP spec (dots allowed, up to 128 chars, only a SHOULD) but is rejected by Anthropic and OpenAI (^[a-zA-Z0-9_-]{1,64}$, no dots). provider/name-pattern catches exactly this class of "works in my host, breaks under that provider" portability bug.

Language-agnostic: lints the wire, not the source

mcpconform never parses your server's source code, so it doesn't care whether the server is Python, Node, Go, Rust, or a compiled binary. MCP is a wire protocol — a Python server and a Node server emit byte-identical tools/list JSON — so the linter validates that protocol surface, not the implementation.

The launch command for inspect comes from the config, so python server.py, node server.js, uvx foo, npx bar, a binary, or a Docker image are all handled by one generic path.

Static source analysis — extracting tool decorators without running the server — is a deliberate non-goal: it would need a parser per framework (FastMCP, the TS SDK, mcp-go, …) and re-break on every framework change. Linting the wire keeps mcpconform both language- and framework-agnostic.

Severity tiers

Every rule lives in rules.json with an id, a tier, and a source citation. Three tiers:

  • error — spec MUST, or a provider would 400 the request.
  • warn — spec SHOULD.
  • info — opinionated quality and portability checks.

Targeting and per-rule severity overrides live in mcpconform.config.json (see mcpconform.config.example.json).

Contributing

See CONTRIBUTING.md. The short version: providers and hosts are data (profiles/*.json), rules are data + a check (rules.json + src/), and the engine stays vendor-agnostic. Keep verified honest and add a test for any rule change.

License

MIT

Ver o original no GitHub

Bom para

Relacionados