@povio/mcp

NestJS kernel for Model Context Protocol servers: Streamable HTTP transport, OAuth authorization server, tool loading, and REST endpoint auto-registration.

The package is developed in this monorepo. Release artifacts are produced only by its version-tag publishing workflow. The host application supplies McpConfig and McpAuthorizer (plus OAuth persistors) through McpModule.forRoot plugins.

Installation

bun add @povio/mcp

Peer dependencies (install in the host app):

• @nestjs/common, @nestjs/core, @nestjs/jwt, @nestjs/swagger ^11
• nestjs-zod ^5
• zod ^3 or ^4
• rxjs ^7
• express >= 4
• fastify >= 4 (optional; required when { httpAdapter: 'fastify' })

Inside this monorepo, consume the package through the workspace:

{
  "dependencies": {
    "@povio/mcp": "workspace:*"
  }
}

Usage

import { McpModule } from "@povio/mcp";

McpModule.forRoot([McpPlugin, McpOAuthClientsPersistorPlugin, McpOAuthSessionPersistorPlugin], {
  httpAdapter: "fastify",
});

forRoot plugins must provide:

• { provide: McpConfig, useValue/useFactory: ... } — parsed MCP configuration
• { provide: McpAuthorizer, useClass: ... } — authorization port
• persistors for OAuth clients and sessions (memory plugins ship with this package; Prisma adapters live in the host)

Mount a resource with McpModule.forResource({ resource, path, authCheck }) from a feature module. Default httpAdapter is 'express'. Pass { httpAdapter: 'fastify' } on Fastify hosts — the Express OAuth handlers assign req.url, which is readonly on Fastify.

Publishing

Release builds and publishing follow the same package workflow as the UI Kit:

VERSION=v1.0.0-mcp bun run lib:build
bun run lib:publish

Stable tags use v<version>-mcp and publish under the npm latest tag. Release candidates use v<version>-rc.<number>-mcp and publish under next. Do not create a GitHub Release for RCs.

The GitHub Actions workflow (.github/workflows/publish-mcp.yml) publishes tagged releases through npm trusted publishing. There is no NPM_TOKEN.

Before the first publish, an @povio org admin must configure a trusted publisher on npmjs.com:

1. Create a pending trusted publisher for @povio/mcp (the package is unpublished until the first tag succeeds).
2. Set the GitHub repository to povio/monorepo-template and the workflow filename to publish-mcp.yml.
3. Confirm the publisher has rights on the @povio org.

If pending publishers are unavailable, first publish with a one-time granular npm token, then switch to trusted publishing. Do not push a release tag until the publisher is configured — the workflow will fail authentication.

Example:

git tag v0.1.0-rc.1-mcp
git push origin v0.1.0-rc.1-mcp