convez.ai
MCP ServerIntegração & APIsAvançado
ninemindai

AgentBack

ninemindai/agentback

Um schema, todos os limites: API + MCP + docs unificados com Zod

Ver no GitHub
BomPluginScore · de 0 a 100

Framework AI-nativo para APIs e servidores MCP que unifica contratos REST, MCP tools e documentação através de um único schema Zod. Baseado em injeção de dependência com Context e Binding, oferece validação em tempo de execução, geração automática de OpenAPI 3.1, segurança integrada (confirmação, idempotência) e suporte a precificação por chamada.

Instalação

$npx convez-ai ninemindai/agentback

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
36
Forks
5
Acompanhando
1
Saúde
50%
Último commit
há 1 semana
Versão
v0.13.0
Issues abertas
2
Contribuidores
1

Casos de uso

  • Construir APIs consumidas simultaneamente por aplicações e agentes IA
  • Gerar ferramentas MCP tipadas automaticamente a partir de schemas
  • Implementar rotas REST e tools MCP com decoradores compartilhados
  • Adicionar segurança (confirmação de payload, idempotência) em APIs de agentes
  • Metrificar e cobrar por uso de ferramentas MCP com custo por chamada

Veredito

Solução sofisticada e bem-arquitetada para times que precisam de APIs multi-consumidor (aplicações + agentes). Alpha estável com testes end-to-end, mas exige familiaridade com DI e Zod; compensador para stacks que unificam REST/MCP.

README

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

AgentBack

AgentBack is an AI-native API/MCP framework for the agent era, built with agents, for agents. It lets REST endpoints, MCP tools, generated docs, typed clients, tests, and runtime validation all share one Zod contract.

The foundation is a modern ESM port of LoopBack 4's proven dependency-injection core: a hierarchical Context of Bindings with @inject, providers, interceptors, extension points, lifecycle observers, and tag-based discovery. REST controllers and MCP tool classes are just bindings the respective servers find by tag. The same schemas attached to those bindings become the runtime validator, z.infer type, OpenAPI 3.1 contract, MCP input/output schema, and Swagger/Inspector-rendered docs.

  • ESM-only, Node 22.13+, TypeScript 6.0
  • Context + Binding DI with @inject, providers, interceptors, extensions, lifecycle observers
  • Zod-first schemas; decorators accept ZodType directly
  • OpenAPI 3.1.1 emission via Zod v4's native z.toJSONSchema
  • MCP (Model Context Protocol) server with the same decorator style as REST
  • Swagger UI at /explorer and MCP Inspector at /mcp-inspector
  • AX artifacts: /llms.txt + /llms-full.txt served from the same route registry
  • Machine-actionable errors: stable codes, per-field issues, the violated schema, retryability, and remediation hints — same envelope on REST and MCP
  • Safety primitives: confirm: (payload-bound confirmation tokens) and idempotency: (idempotency-key replay) on routes and tools
  • Tool cost report: token-price the MCP tool surface before agents pay for it
  • Per-call pricing: @price('$0.001') meters a route or tool and (with installPriceGate) refuses unpaid calls with an x402/MPP challenge
  • Typed HTTP client without codegen when TypeScript consumers share schemas
  • Policy, auth, metering, payments, messaging, and observability as DI components
  • Built on the official @modelcontextprotocol/sdk

Status: alpha. End-to-end examples and tests pass; the API surface is stabilizing but may still change between alpha releases.

Positioning

The core product claim is one schema, every boundary. Compared with common Node/TypeScript service stacks, AgentBack optimizes for teams whose APIs are consumed by both applications and AI agents.

StackRuntime contractService contractAgent/tool contract
Express + raw ZodHand-wired ZodHand-written OpenAPIHand-written tool manifest
tRPCZodTypeScript-onlyCustom adapter
NestJSclass-validatorSwagger decoratorsCustom adapter
FastAPIPydanticOpenAPI from the same modelsCustom adapter
AgentBackZodOpenAPI from same ZodMCP from same Zod

Use it when you need HTTP APIs, MCP tools, docs, typed clients, policy checks, and usage rails to stay coherent as the system grows.

Documentation

Full docs live in docs/ — a guided path from the core ideas to building real apps:

The rest of this README is the one-page tour and code feel.

Packages

The DI framework is the foundation; everything else is built on it.

DI foundation

PackageRole
@agentback/commonShared logging, env, ID, redaction, and async helper utilities
@agentback/metadataDecorator metadata utilities (port of @loopback/metadata)
@agentback/contextDI container: Context, Binding, @inject, providers, interceptors (port of @loopback/context)
@agentback/coreApplication (a Context), Component, Server, life-cycle (port of @loopback/core)

REST, MCP, and clients

PackageRole
@agentback/http-serverHTTP server with graceful stop (port of @loopback/http-server)
@agentback/expressExpress integration + middleware (port of @loopback/express)
@agentback/openapiZod-first decorators + OpenAPI 3.1.1 emission
@agentback/restMinimal REST server with Zod request/body validation
@agentback/rest-explorerMounts Swagger UI 5.x at /explorer
@agentback/context-explorerMounts a context/binding explorer UI
@agentback/schema-explorerMounts a schema/entity provenance explorer UI (REST + MCP + Drizzle)
@agentback/mcpDecorator-driven MCP server (@mcpServer, @tool w/ Zod input/output)
@agentback/mcp-inspectorMounts an MCP inspector UI at /mcp-inspector
@agentback/mcp-httpExposes the MCP server over Streamable HTTP at /mcp (+ OAuth, scopes)
@agentback/mcp-clientConnect to remote MCP servers over HTTP (OAuth-aware)
@agentback/mcp-hostAggregate upstream MCP servers into one gateway
@agentback/mcp-connectPersistent outbound MCP connections for browser/admin UIs
@agentback/clientSchema-shared typed HTTP client with no codegen

Platform components

PackageRole
@agentback/configZod-validated config loader with env overlays and DI bindings
@agentback/securityUser, subject, and principal primitives
@agentback/authenticationAuthentication decorator and strategy pipeline
@agentback/authentication-jwtJWT bearer strategy
@agentback/authentication-oauth2OAuth2 introspection and JWKS bearer-token strategies
@agentback/authorization@authorize decorator and voter pipeline
@agentback/extension-healthHealth/readiness probes
@agentback/extension-metricsPrometheus /metrics endpoint and HTTP timing
@agentback/extension-otelOpenTelemetry spans across REST, MCP, and jobs
@agentback/extension-rate-limitIn-memory or Redis-backed rate limiting
@agentback/meteringPer-principal REST/MCP usage events, audit sinks, and quota
@agentback/paymentsx402/MPP/Stripe payment authorization and billing seams
@agentback/messagingZod-typed JobQueue/EventBus/Scheduler ports with in-memory adapter
@agentback/messaging-bullmqBullMQ + Redis Streams durable adapter for messaging ports
@agentback/drizzleDrizzle ORM binding and drizzle-zod recipe
@agentback/filesFileStore port for uploads/downloads + in-memory & filesystem adapters
@agentback/files-s3S3 FileStore adapter (streaming via AWS SDK v3)
@agentback/pluginPlugin discovery, gating, and component mounting
@agentback/testingTest harness with typed REST client, supertest, and in-memory MCP
@agentback/testlabLower-level test helpers used by the package test suites
create-agentbacknpm create scaffold for REST, MCP, and hybrid services
@agentback/consoleCombined context, schema, REST/OpenAPI, and MCP admin console
@agentback/console-themeShared styling for console and explorer UIs

Quick start

pnpm install
pnpm build
pnpm -F hello-rest start    # REST + Swagger UI
pnpm -F hello-mcp test      # MCP over stdio (drives the server with a test client)
pnpm -F hello-hybrid start  # REST + MCP from one process, both UIs

Reference app

For a complete, real-world build beyond the in-repo hello-* examples, see ninemindai/agentback-demo — a Weather MCP server where one Zod schema set is served over stdio, authenticated HTTP, and a dev console, backed by the free Open-Meteo API.

For coding agents (Claude Code, Codex, …)

This repo ships an agent skill — skills/agentback — that teaches a coding agent the framework's decorator patterns, slot-0 input-bundle convention, DI container, auth stack, and schema-sharing client, with task-scoped reference files the agent loads on demand. If you're building an app with AgentBack and an agent is doing the typing, install the skill first; it encodes the conventions that aren't guessable from type signatures alone.

The easiest install is skills.sh, which supports Claude Code, Codex, Cursor, Copilot, Gemini, and 20+ other agents:

npx skills add ninemindai/agentback            # pick agents interactively
npx skills add ninemindai/agentback -a claude-code -a codex -y
npx skills add ninemindai/agentback -g -y      # user-global, all agents

Once installed, the agent discovers it automatically; it activates when a task mentions @agentback/* packages, the REST/MCP decorators, or hybrid Zod-shared apps.

Agents without skill support — the skill is plain markdown with a YAML description. Point the agent at it from your instructions file (e.g. AGENTS.md):

When working with @agentback/\* packages, first read
skills/agentback/SKILL.md and the relevant file under
skills/agentback/references/ (REST, MCP tools, DI, auth, client sharing,
or composition) before writing code.

The skill's references/ directory splits the deep material by task — rest-and-openapi.md, mcp-tools.md, dependency-injection.md, auth-and-rate-limiting.md, schema-sharing-and-client.md, composition-and-operations.md — so agents pull only the context the current task needs.

A 30-second feel

DI container (works standalone, no HTTP needed)

import {Context, BindingScope, inject, injectable} from '@agentback/context';
import {Application} from '@agentback/core';

@injectable({scope: BindingScope.SINGLETON})
class Clock {
  now() {
    return new Date().toISOString();
  }
}

@injectable()
class Greeter {
  constructor(@inject('clock') private clock: Clock) {}
  greet(name: string) {
    return `Hello ${name} at ${this.clock.now()}`;
  }
}

const app = new Application(); // Application IS a Context
app.bind('clock').toClass(Clock);
app.service(Greeter); // tag-based service binding

const greeter = await app.get<Greeter>('services.Greeter');
console.log(greeter.greet('world'));

The same Context/Binding/@inject machinery is what the REST and MCP servers below use under the hood — controllers and tool classes are just tagged bindings the servers discover at start time.

REST controller (Zod-validated)

import {z} from 'zod';
import {api, get, post} from '@agentback/openapi';
import {RestApplication} from '@agentback/rest';
import {inject} from '@agentback/context';

const HelloPath = z.object({name: z.string().min(1).max(64)});
const Greeting = z.object({greeting: z.string()});
const EchoIn = z.object({text: z.string().min(1).max(280)});
const EchoOut = z.object({echoed: z.string(), at: z.string()});

@api({basePath: '/greet'})
class GreetingController {
  @get('/hello/{name}', {path: HelloPath, response: Greeting})
  async hello(input: {path: z.infer<typeof HelloPath>}) {
    return {greeting: `Hello, ${input.path.name}!`};
  }

  @post('/echo', {body: EchoIn, response: EchoOut})
  async echo(
    input: {body: z.infer<typeof EchoIn>},
    @inject('clock') clock: {now(): string},
  ) {
    return {echoed: input.body.text, at: clock.now()};
  }
}

const app = new RestApplication();
app.bind('clock').to({now: () => new Date().toISOString()});
app.restController(GreetingController);
await app.start();
// GET /openapi.json -> OpenAPI 3.1.1
// POST /greet/echo with {"text":""} -> 422 with Zod issues

Schemas live once on each verb decorator. The handler receives a single input object with body/path/query/headers keys derived via z.infer — change a schema and the parameter type updates. @inject weaves in at slot 1+; on routes with no input schemas, slot 0 is yours too (e.g. @get('/whoami') async whoami(@inject(USER) user) { … }).

MCP tool class

import {z} from 'zod';
import {mcpServer, tool, MCPComponent} from '@agentback/mcp';

const ForecastInput = z.object({
  city: z.string(),
  days: z.number().int().min(1).max(7),
});
const ForecastOutput = z.object({
  city: z.string(),
  forecast: z.string(),
});

@mcpServer()
class WeatherTools {
  @tool('get_forecast', {
    description: 'Returns the forecast for a city.',
    input: ForecastInput,
    output: ForecastOutput,
  })
  async getForecast(input: z.infer<typeof ForecastInput>) {
    return {city: input.city, forecast: 'sunny'};
  }
}

const app = new RestApplication();
app.component(MCPComponent); // registers MCPServer
app.service(WeatherTools); // tag flows from @mcpServer's @bind metadata
await app.start();
// stdio MCP transport active by default; mount mcp-inspector for a UI

The schemas live once, on the decorator. The parameter type is derived via z.infer<typeof ForecastInput> — if you change the schema, TS rewrites the parameter type. With output: declared, the return type is also constrained at compile time and validated at runtime; the MCP SDK is given the schema so structured-content clients can consume it directly. Omit output: to keep the method's return type unconstrained.

The @mcpServer() decorator uses @bind({tags: {mcpServer: true}}) under the hood. When you bind the class with app.service() (or app.controller()), the framework reads that metadata via createServiceBinding and the mcpServer tag is applied automatically — no manual .tag() call needed.

The agent-native contract

Beyond schemas, the framework ships the conventions agents need from an API:

@post('/deploy', {body: DeployIn, response: DeployOut, confirm: true})
async deploy(input: {body: z.infer<typeof DeployIn>}) { … }
// 1st call -> 409 {error: {code: 'confirmation_required', confirmationToken, hint}}
// identical retry with x-confirmation-token header -> executes.
// The token is single-use and bound to the exact payload — a confirmed
// call cannot differ from the proposed one. Same flow on MCP tools via
// @tool(..., {confirm: true}) and a `confirmationToken` input property.

@post('/charge', {body: ChargeIn, response: ChargeOut, idempotency: true})
async charge(input: {body: z.infer<typeof ChargeIn>}) { … }
// Replaying an idempotency-key header returns the original result without
// re-executing; concurrent duplicates share one execution; errors aren't cached.
  • Errors are machine-actionable. Every failure is {error: {statusCode, code, message, issues?, schema?, retryable, hint?}} — a stable code (never parse message), per-field issues, the violated section's JSON Schema inline, and a one-line remediation hint. MCP tool errors carry the same envelope as REST, so one parser self-corrects on both surfaces.
  • The API documents itself to agents. app.start() serves /llms.txt (compact endpoint index) and /llms-full.txt (full inlined schemas) from the same registry as /openapi.json; generateAgentContext() renders an agent-context manual (CLAUDE.md shape) for the live API. Components append sections via the AX_SECTION_TAG binding tag — installMcpHttp adds the MCP tool listing automatically.
  • Tool definitions are a context budget. mcpServer.toolCostReport() token-prices every tools/list entry and totals what each connection costs a caller's context window; formatToolCostReport() flags over-budget tools.

Design pivots from the upstream LoopBack 4

Three packages were rewritten rather than ported wholesale because the upstream code carries baggage the fork doesn't want:

  • openapi — the upstream @loopback/openapi-v3 is built around openapi3-ts@2.x loose types and a JSON-Schema-via- @loopback/repository-json-schema pipeline. We emit OpenAPI 3.1.1 directly from Zod via z.toJSONSchema({target: 'draft-2020-12'}), which aligns with OpenAPI 3.1's dialect.
  • rest — the upstream @loopback/rest is ~10k LoC of sequences, actions, and middleware composition. We have a minimal RestServer that handles routing, Zod request/body validation, error mapping, and serves the OpenAPI document.
  • mcp-inspector — the official @modelcontextprotocol/inspector is a CLI tool, not an embeddable UI. We ship a small DOM-built inspector that talks to the in-process MCPServer directly via a JSON API.

The DI foundation (metadata, context, core) and the http-server / express integrations are faithful ESM ports — same source as upstream LoopBack 4, with .js extensions on relative imports, lodash → lodash-es, and p-event v6 named exports. The DI semantics (binding scopes, @inject, providers, interceptors, extension points, observers) match @loopback/context and @loopback/core exactly; if you know LB4 DI, you already know this.

What's deferred

Truly out of scope for v0

These are deliberately not in the framework — they reintroduce the upstream complexity the rewrite walked away from.

  • LB4 sequences/actions (findRoute → parseParams → invoke → send → reject DI pipeline). RestServer is a monolithic dispatcher; per-route customization lives on the decorator, cross-cutting in middleware/interceptors, and deeper changes in subclassing RestServer and overriding dispatch / sendResult / sendError.
  • @loopback/repository and the Filter<T> / Where<T> helpers.
  • x-ts-type inlining — replaced by Zod schemas attached to route metadata.
  • @oas.deprecated / @oas.tags / @oas.visibility decorator namespace.

Already available, just not as polished

  • Middleware composition — @agentback/express ships the LB4 middleware machinery, and RestApplication exposes app.middleware(...) and app.expressMiddleware(...). Registered middleware runs through the framework's chain before every route handler.
  • CORS — set cors: true (or pass CorsOptions) on RestServerConfig; the cors package is mounted globally.
  • MCP over Streamable HTTP — @agentback/mcp-http's installMcpHttp(app) exposes the in-process MCP server at /mcp so remote clients (Claude, Cursor) can reach the same tools; stdio remains the default. Supports OAuth 2.1 resource-server protection (auth: option + /.well-known/oauth-protected-resource), scope-based tool ACL (@tool(..., {scope})), and DNS-rebinding protection.

Not yet implemented

  • MCP SSE (legacy) transport — Streamable HTTP is supported; the older SSE transport is not.
  • MCP resource/prompt aggregation in the gateway — @agentback/mcp-host aggregates upstream tools today; resource/prompt routing is a straightforward follow-on.

About the test story

We use Vitest (2000+ tests across the workspace), not LB4's mocha/should ports. Tests run against built dist/ — pnpm build before pnpm test.

Development

Contributions welcome — see CONTRIBUTING.md for setup, conventions, and the proposal process.

pnpm install          # install all workspace deps
pnpm build            # tsc -b across the workspace
pnpm test             # vitest run — IMPORTANT: requires a prior `pnpm build`
pnpm -F <pkg> build   # build a single package

Tests run against built dist/. vitest.config.ts globs packages/*/dist/__tests__/**/*.{test,spec,unit,integration,acceptance}.js, so editing a .ts file requires pnpm build (or pnpm build:watch) before pnpm test sees the change.

TypeScript project references keep incremental builds fast. ESLint flat config + Prettier match the LB4 conventions (single quotes, no bracket spacing, 80 col).

A note on the verb/tool input shape

Schemas live on the decorator (@get/@post/...'s options object, @tool's input/output). The handler always receives one positional input bundle whose type is derived via z.infer. @inject parameters live at slot 1+ when schemas are declared; when no schemas are declared, slot 0 is free for @inject too. The slot-0 reservation is enforced at decoration time, and URL placeholders are cross-checked against the path: schema at app.start().

License

MIT.

Ver o original no GitHub

Bom para

Relacionados