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 @ApTool and classes with @ApModule to expose them as AI tools
• Auto-discovery — ApToolScannerService scans 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, createBridgeContext
• JWTAuthenticator, 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