convez.ai
MCP ServerSegurançaAvançado
dtkmn

MCP Gateway Core

dtkmn/mcp-gateway-core

Contratos Java de governança para gateways MCP — sem proxy data plane

Ver no GitHub
InicialPluginScore · de 0 a 100

Biblioteca Java que fornece contratos de governança reutilizáveis para gateways MCP, incluindo identidade de ferramentas, autorização, políticas, auditoria e rate limiting. Não é um gateway completo, mas uma camada contratual para que runtimes Java integrem segurança e governança de ferramentas MCP sem adotar um proxy runtime full.

Instalação

$npx convez-ai dtkmn/mcp-gateway-core

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
3
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 2 dias
Versão
v0.11.1
Issues abertas
1
Contribuidores
1

Casos de uso

  • Implementar autorização e políticas em servidores MCP Java
  • Adicionar auditoria e rate limiting a invocações de ferramentas MCP
  • Construir packs de segurança MCP com contratos padronizados

Veredito

Ferramenta especializada para engenheiros Java construindo gateways MCP. Oferece contratos bem desenhados para governança sem impor infraestrutura de proxy, ideal para quem quer controle fino sobre autenticação e políticas em runtimes customizados ou Spring.

README

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

MCP Gateway Core

Core Maven Central Spring WebFlux Adapter Maven Central Java

Java governance contracts and primitives for MCP tool gateways.

This repository is intentionally small. It provides MCP-neutral Java value types and helpers that downstream gateway runtimes can use for tool identity, authorization, policy decisions, audit events, abuse protection, URL scoping, correlation IDs, and rate limiting. It also publishes an optional Spring WebFlux adapter for Java runtimes that want ready-made HTTP filters around those core contracts.

It is not a gateway runtime, router, scanner integration, UI, service mesh, or traffic-management data plane.

Current status: public preview. The package and coordinate are intended for early integration proof, not a stable compatibility promise.

Architecture At A Glance

flowchart LR
    Client["MCP client"]
    Runtime["Downstream MCP runtime<br/>Spring app, custom server, security pack"]
    Adapter["Optional adapter<br/>mcp-gateway-spring-webflux"]
    Core["Core contracts<br/>mcp-gateway-core"]
    Product["Product-specific tools<br/>scanner, database, files, internal APIs"]

    Client --> Runtime
    Runtime --> Adapter
    Runtime --> Core
    Adapter --> Core
    Runtime --> Product

    Core -. owns .-> Contracts["tool identity<br/>authz decisions<br/>policy rules<br/>audit events<br/>quotas and rate limits"]
    Product -. owns .-> Behavior["tool behavior<br/>storage<br/>auth provider<br/>observability backend"]

Why This Exists

MCP servers need a reusable governance layer around tool calls: identify the tool, decide whether the caller may invoke it, apply quotas and rate limits, record audit events, and keep product-specific integrations out of the shared contract.

mcp-gateway-core is that contract layer. mcp-gateway-spring-webflux is a thin framework adapter over the same contracts. Downstream projects still own their transport setup, authentication provider, storage, observability backend, and domain-specific tool behavior.

Relationship To Runtime Gateways

Runtime gateway projects such as agentgateway provide a gateway control plane and proxy/data plane for routing, securing, and observing MCP, LLM, A2A, and other agent traffic.

mcp-gateway-core is deliberately narrower. It is a Java library for reusable MCP tool-governance contracts: tool descriptors, authorization requirements, policy decisions, audit events, abuse-protection decisions, and small helper primitives.

Use a runtime gateway when you need traffic routing, proxying, Kubernetes Gateway API integration, backend federation, or data-plane operations. Use mcp-gateway-core when you are building an MCP gateway/security pack and need a shared Java contract for tool-level governance without adopting a full proxy runtime.

Scope

Included:

  • MCP tool invocation contracts
  • MCP tool identity, surface, capability, and access-registry contracts
  • MCP tool authorization request, requirement, registry, authorizer, and evaluator contracts
  • policy decision and policy-bundle evaluation contracts
  • audit event, sink, and emitter contracts
  • abuse-protection context and quota decision contracts
  • correlation ID helpers
  • URL-scope helpers
  • token-bucket rate limiting primitives
  • gateway execution context and principal/workspace model
  • optional Spring WebFlux request filters and JSON-RPC parsing adapters

Excluded:

  • scanner integrations
  • report, finding, queue, or evidence storage
  • Spring Boot application wiring or auto-configuration
  • enterprise packaging
  • A2A, LLM-provider, service-mesh, or Kubernetes gateway implementation
  • product-specific tool names from downstream security packs

For package-by-package detail, see the module map.

For practical integration examples, see the getting started guide. For field and value semantics, see the contract reference.

Module Map

AreaPackage
MCP invocationmcp.gateway.core.invocation
Tool descriptors and registrymcp.gateway.core.tool
Execution contextmcp.gateway.core.context
Authorizationmcp.gateway.core.authz
Policy decisionsmcp.gateway.core.policy
Policy bundle evaluationmcp.gateway.core.policybundle
Audit eventsmcp.gateway.core.audit
Abuse protection and quota decisionsmcp.gateway.core.protection
Rate limitingmcp.gateway.core.rate
Correlation IDsmcp.gateway.core.logging
URL scope checksmcp.gateway.core.url
Spring WebFlux adaptermcp.gateway.spring.webflux

The core artifact remains JDK-only. The Spring WebFlux adapter is separate so runtime projects can choose it without forcing Spring onto core consumers. Storage, scanner, and product behavior stay outside both artifacts.

Repository Layout

core/                       # publishes io.github.dtkmn:mcp-gateway-core
adapters/spring-webflux/    # publishes io.github.dtkmn:mcp-gateway-spring-webflux

The root Gradle project only coordinates shared verification tasks. It is not a published artifact.

Build

./gradlew verifyGatewayPublicPreviewPublication --no-daemon --stacktrace

This command runs the core and adapter builds, forbidden-coupling checks, closed-world JAR checks, Java 17 bytecode checks, adapter runtime-classpath bytecode checks, core jdeps, unsigned Central Portal bundle validation, and signed dry-run bundle validation with an ephemeral local GPG key.

Coordinates

Core coordinate:

io.github.dtkmn:mcp-gateway-core:0.5.9

Optional Spring WebFlux adapter coordinate:

io.github.dtkmn:mcp-gateway-spring-webflux:0.5.9

Gradle:

implementation "io.github.dtkmn:mcp-gateway-core:0.5.9"
implementation "io.github.dtkmn:mcp-gateway-spring-webflux:0.5.9" // optional

Maven:

<dependency>
  <groupId>io.github.dtkmn</groupId>
  <artifactId>mcp-gateway-core</artifactId>
  <version>0.5.9</version>
</dependency>
<dependency>
  <groupId>io.github.dtkmn</groupId>
  <artifactId>mcp-gateway-spring-webflux</artifactId>
  <version>0.5.9</version>
</dependency>

Local Staging

./gradlew :core:publishGatewayCorePublicationToGatewayCoreStagingRepository \
  :adapters:spring-webflux:publishGatewaySpringWebFluxPublicationToGatewayCoreStagingRepository \
  -PgatewayCorePublicationRepositoryUrl="$(pwd)/build/staging-repository" \
  --no-daemon --stacktrace

Release And Compatibility

Security Tooling

The repository uses GitHub-native security automation first:

  • Dependabot version updates for GitHub Actions and Gradle.
  • CodeQL Java analysis with an explicit Gradle test build.
  • Snyk Open Source scanning for the Gradle project graph in .github/workflows/snyk.yml. The workflow requires a real SNYK_TOKEN secret, accepts optional SNYK_ORG as a secret or variable for explicit organization routing, fails visibly when the token is absent, uploads SARIF for review, and then enforces the Snyk exit code.
  • The Gradle public-preview verification gate for forbidden coupling, closed-world JAR contents, jdeps, Central bundle shape, checksums, and signed dry-run payload validation.

The Snyk workflow is external dependency scanning. It does not publish, promote, or change the manual public-preview release path.

Documentation Site

The public documentation site is built with Astro Starlight from docs-site/ and deployed to GitHub Pages:

npm --prefix docs-site run build

The site syncs source Markdown from docs/ and SECURITY.md before each build so the repository README/docs remain the editing source of truth.

Future Plan

The short version: prove boring governance contracts through real downstream consumers before claiming stable API or broader gateway-runtime scope.

See the roadmap for graduation criteria and non-goals.

Ver o original no GitHub

Bom para

Relacionados