Nestjs Apcore
NestJS adapter for the apcore AI-Perceivable module ecosystem
Ask AI about Nestjs Apcore
Powered by Claude Β· Grounded in docs
I know everything about Nestjs Apcore. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
nestjs-apcore
NestJS adapter for the apcore AI-Perceivable module ecosystem. Turn your existing NestJS services into AI-callable MCP tools and OpenAI-compatible function definitions β with zero changes to your business logic.
Features
- Decorator-driven β Mark methods with
@ApTooland classes with@ApModuleto expose them as AI tools - Auto-discovery β
ApToolScannerServicescans all providers at startup and registers decorated methods automatically - Multi-schema support β TypeBox, Zod, class-validator DTOs, and plain JSON Schema, auto-detected via a priority chain
- MCP server built-in β Serve tools over stdio, Streamable HTTP, or SSE transports with optional Tool Explorer UI
- OpenAI-compatible β Convert registered tools to OpenAI function-calling format with
toOpenaiTools() - YAML bindings β Register tools declaratively from YAML files without touching source code
- Dual access β Services remain injectable into REST controllers while simultaneously available as MCP tools
Installation
npm install nestjs-apcore apcore-js apcore-mcp @modelcontextprotocol/sdk js-yaml
Peer dependencies (required):
npm install @nestjs/common @nestjs/core reflect-metadata rxjs
Optional (for schema adapters):
npm install zod # ZodAdapter
npm install class-validator class-transformer # DtoAdapter
npm install @sinclair/typebox # TypeBoxAdapter (recommended)
Requirements: Node.js >= 18, NestJS >= 10
Quick Start
1. Wire up modules
// app.module.ts
import { Module } from '@nestjs/common';
import { ApcoreModule, ApcoreMcpModule, ApToolScannerService } from 'nestjs-apcore';
@Module({
imports: [
ApcoreModule.forRoot({}),
ApcoreMcpModule.forRoot({
transport: 'streamable-http',
port: 8000,
name: 'my-app',
version: '1.0.0',
explorer: true,
}),
TodoModule,
],
providers: [ApToolScannerService],
})
export class AppModule {}
2. Decorate your services
// todo.service.ts
import { Injectable } from '@nestjs/common';
import { Type } from '@sinclair/typebox';
import { ApModule, ApTool } from 'nestjs-apcore';
@ApModule({ namespace: 'todo', description: 'Todo list management' })
@Injectable()
export class TodoService {
private todos = [];
@ApTool({
description: 'List all todos, optionally filtered by status',
inputSchema: Type.Object({
done: Type.Optional(Type.Boolean()),
}),
annotations: { readonly: true, idempotent: true },
tags: ['todo', 'query'],
})
list(inputs: Record<string, unknown>) {
const { done } = inputs;
const filtered = done !== undefined
? this.todos.filter((t) => t.done === done)
: this.todos;
return { todos: filtered, count: filtered.length };
}
@ApTool({
description: 'Create a new todo item',
inputSchema: Type.Object({
title: Type.String(),
}),
annotations: { readonly: false },
tags: ['todo', 'mutate'],
})
create(inputs: Record<string, unknown>) {
const todo = { id: this.todos.length + 1, title: inputs.title, done: false };
this.todos.push(todo);
return todo;
}
}
3. Boot the app
// main.ts
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
async function bootstrap() {
const app = await NestFactory.create(AppModule);
await app.listen(3000);
// MCP server starts automatically on port 8000
}
bootstrap();
Your service is now available as:
- REST API at
http://localhost:3000(via NestJS controllers) - MCP server at
http://localhost:8000(for AI agents) - Tool Explorer at
http://localhost:8000/explorer/(interactive web UI)
API Reference
Modules
ApcoreModule
Provides the core Registry and Executor as NestJS singletons.
// Sync
ApcoreModule.forRoot({ extensionsDir?, acl?, middleware?, bindings? })
// Async (e.g. inject ConfigService)
ApcoreModule.forRootAsync({ imports, useFactory, inject })
ApcoreMcpModule
Configures and starts the MCP server.
The MCP server runs standalone on its own port (e.g. 8000), separate from NestJS's REST server (e.g. 3000). Both share the same Registry and Executor instances.
ApcoreMcpModule.forRoot({
transport: 'stdio' | 'streamable-http' | 'sse',
host?: string,
port?: number,
name?: string,
version?: string,
tags?: string[], // only expose tools matching these tags
prefix?: string, // only expose tools with this ID prefix
explorer?: boolean, // enable Tool Explorer web UI
explorerPrefix?: string, // URL prefix for the Explorer
allowExecute?: boolean, // allow execution from Explorer
dynamic?: boolean, // enable dynamic tool list updates
validateInputs?: boolean,
logLevel?: 'DEBUG' | 'INFO' | 'WARNING' | 'ERROR' | 'CRITICAL',
authenticator?: Authenticator, // JWT or custom auth
exemptPaths?: string[], // paths that bypass auth (default: ['/health', '/metrics'])
metricsCollector?: { exportPrometheus(): string },
onStartup?: () => void | Promise<void>,
onShutdown?: () => void | Promise<void>,
})
Decorators
| Decorator | Target | Description |
|---|---|---|
@ApModule(opts) | Class | Sets namespace for all @ApTool methods (e.g. todo) |
@ApTool(opts) | Method | Registers the method as an AI-callable tool |
@ApContext() | Parameter | Injects the apcore Context object (callerId, trace info) |
@ApTool options
@ApTool({
description: string, // required
id?: string, // auto-generated in snake_case if omitted (e.g. 'email.send_batch')
inputSchema?: any, // TypeBox, Zod, DTO class, or JSON Schema
outputSchema?: any,
annotations?: {
readonly?: boolean,
destructive?: boolean,
idempotent?: boolean,
requiresApproval?: boolean,
openWorld?: boolean,
streaming?: boolean,
},
tags?: string[],
documentation?: string,
examples?: ApToolExample[],
})
Services
| Service | Description |
|---|---|
ApcoreRegistryService | Register/unregister tools, query the registry |
ApcoreExecutorService | Execute tools: call(), stream(), validate() |
ApcoreMcpService | MCP server lifecycle: start(), stop(), restart(), toOpenaiTools() |
ApToolScannerService | Auto-discovers and registers @ApTool decorated methods at startup |
Schema Adapters
Schemas are auto-detected and converted via a priority chain:
| Adapter | Priority | Input |
|---|---|---|
| TypeBoxAdapter | 100 | @sinclair/typebox schemas |
| ZodAdapter | 50 | Zod schemas |
| JsonSchemaAdapter | 30 | Plain JSON Schema objects |
| DtoAdapter | 20 | class-validator decorated DTO classes |
YAML Bindings
Register tools without decorators:
bindings:
- module_id: email.send
target: EmailService.send
description: Send an email
input_schema:
type: object
properties:
to: { type: string }
subject: { type: string }
body: { type: string }
tags: [email, mutate]
annotations:
readonly: false
JWT Authentication
Enable JWT auth by passing a JWTAuthenticator to ApcoreMcpModule. The Explorer UI and /health endpoint are always exempt.
import { JWTAuthenticator, getCurrentIdentity } from 'nestjs-apcore';
// In app.module.ts
const jwtSecret = process.env.JWT_SECRET;
ApcoreMcpModule.forRoot({
transport: 'streamable-http',
port: 8000,
authenticator: jwtSecret ? new JWTAuthenticator({ secret: jwtSecret }) : undefined,
})
// Inside any @ApTool method
list(inputs: Record<string, unknown>) {
const caller = getCurrentIdentity()?.id ?? 'anonymous';
return { items: [...], caller };
}
JWTAuthenticator options: secret, algorithms (default ['HS256']), audience, issuer, claimMapping, requireClaims, requireAuth (default true).
Re-exported Utilities
From apcore-mcp:
reportProgress,elicit,createBridgeContextJWTAuthenticator,getCurrentIdentity,identityStorage
Examples
The demo/ directory contains a full working app with Todo and Weather services:
cd demo
npm install
npx tsx src/main.ts
Or with Docker:
cd demo
docker compose up --build
Scripts
| Command | Description |
|---|---|
npm run build | Compile TypeScript |
npm run dev | Watch mode compilation |
npm test | Run tests (vitest) |
npm run test:watch | Run tests in watch mode |
npm run test:coverage | Run tests with coverage |
npm run typecheck | Type-check without emitting |
npm run lint | Lint source and tests |
License
Apache-2.0
