@onivoro/server-mcp

Enables developers to define MCP tools using NestJS decorators (@Tool, @ToolInput, etc.) that generate strongly-typed tool schemas at compile time. The decorator system introspects TypeScript types and generates JSON Schema automatically, eliminating manual schema duplication and enabling IDE autocomplete for tool parameters. This approach leverages NestJS's dependency injection container to manage tool lifecycle and metadata.

Provides a unified tool registry that can be exposed over multiple transports (HTTP, stdio, direct in-process) without changing tool implementation code. The registry uses an adapter pattern where each transport (HTTP server, stdio handler, direct function calls) binds to the same underlying tool definitions, allowing a single tool service to serve multiple MCP clients simultaneously through different protocols.

Automatically serializes tool execution results to transport-appropriate formats (JSON for HTTP/stdio, native objects for direct invocation) while preserving type information and handling complex types (dates, buffers, custom objects). The serialization layer uses NestJS interceptors to transform tool results before sending them to clients, ensuring consistent formatting across transports and enabling custom serialization strategies for domain-specific types.

Exposes the tool registry as an HTTP server with JSON request/response handling that maps HTTP POST requests to tool invocations. The HTTP transport implements MCP protocol semantics over REST, handling tool discovery (list tools), tool execution (call tool), and error responses. Built on NestJS controllers, it integrates with the framework's middleware, guards, and exception handling for production-grade HTTP service behavior.

Exposes the tool registry over stdin/stdout using the MCP JSON-RPC protocol, enabling integration with CLI tools, local agents, and development environments. The stdio transport reads JSON-RPC messages from stdin, routes them to the tool registry, and writes responses to stdout, implementing full MCP protocol semantics including tool discovery, execution, and error handling without requiring a network connection.

Allows tools to be invoked directly from within the same Node.js process by accessing the tool registry programmatically, bypassing transport layers entirely. This capability leverages NestJS dependency injection to provide direct access to tool instances, enabling unit testing, internal service-to-service tool calls, and development-time tool exploration without serialization overhead or network latency.

Provides endpoints or methods to discover all available tools and their schemas without manual registration or configuration. The discovery mechanism scans the tool registry (populated via decorators) and returns tool metadata including names, descriptions, input schemas, and output schemas in a standardized format. This enables MCP clients to dynamically discover capabilities at runtime without hardcoding tool names or schemas.

Validates tool invocation parameters against auto-generated JSON Schema and coerces input types to match tool signatures. The validation pipeline uses NestJS pipes to intercept tool calls, validate inputs against the schema, and transform raw request data (strings, numbers from HTTP/stdio) into properly-typed TypeScript objects before passing them to tool implementations. This ensures type safety and prevents invalid tool invocations.

Catches exceptions thrown by tools and maps them to standardized MCP error responses with appropriate error codes and messages. The error handling layer uses NestJS exception filters to intercept tool execution errors, extract relevant error information, and format responses according to MCP protocol specifications. This ensures that tool failures are communicated consistently to clients regardless of transport (HTTP, stdio, or direct).

Enables tool definitions to be shared across multiple services and applications within a monorepo through NestJS module exports and dependency injection. Tools can be defined in a shared library module, imported into multiple service modules, and exposed through different transports in different applications — all without code duplication. The library supports composing tool services from multiple modules, enabling teams to organize tools by domain or feature.

Provides access to execution context (caller identity, request metadata, trace IDs) within tool implementations through NestJS request scope and context injection. Tools can access information about who invoked them, which transport was used, and other request metadata without explicit parameter passing. This enables tools to implement audit logging, access control, and request tracing without modifying tool signatures.