nitro-mcp-server copilot-instructions.md

Copilot Instructions for Nitro MCP Server

Project Overview

This is a Model Context Protocol (MCP) server implementation using Nitro framework with streamable HTTP transport. It demonstrates MCP server capabilities including tools, resources, prompts, and pluggable authentication providers.

Technology Stack

• Runtime: Nitro (v2.12.4+)
• MCP SDK: @modelcontextprotocol/sdk (v1.17.3+)
• Validation: Zod (v3.25.76+)
• Auth: JWT with jose library
• Logger: consola (v3.4.2+)
• Package Manager: pnpm (v10.7.1+)
• TypeScript: v5.9.2+
• ESLint: @antfu/eslint-config (v5.2.1+)

Code Style & Conventions

TypeScript

• Use TypeScript for all source files
• Prefer type imports: import type { TypeName } from '...'
• Use Zod schemas for runtime validation
• Define explicit return types for public functions
• Use interface for object shapes, type for unions/intersections

Formatting

• Use single quotes for strings
• 2-space indentation
• Follow @antfu/eslint-config rules
• No semicolons (per config)
• Use arrow functions for callbacks
• Prefer const over let

File Organization

• Group imports by: types, external libraries, internal modules, utilities
• Export reusable types from ~/types.ts
• Keep route handlers in routes/ directory
• Place business logic in lib/ directory
• Utils in utils/ for reusable helpers
• Plugins in plugins/ for Nitro plugins
• Middleware in middleware/ for global handlers

Architecture Patterns

MCP Server Structure

The MCP server is initialized in plugins/mcp.ts.

1. Server Initialization: Create McpServer instance with name, version, and capabilities
2. Registration: Register tools, resources, and prompts from arrays
3. Singleton Pattern: Export getServer() and getAuthProvider() for accessing instances

Tools (in lib/tools/)

Tools are MCP functions that can be invoked by clients.

Key Points:

• Always validate input with Zod schemas
• Use structuredContent for typed outputs when outputSchema is defined
• Always provide fallback content array
• Access auth info from second parameter: { authInfo }
• Use logger for logging operations
• Add tool to tools array in plugins/mcp.ts