marvel-mcp copilot-instructions.md

Marvel MCP Server Development Guide

Project Overview

This is a Model Context Protocol (MCP) server that provides AI tools access to the Marvel Comics API. The server exposes 6 main tools for fetching Marvel characters and comics data through a standardized MCP interface.

Architecture

Core Components

• Entry Point: src/index.ts - MCP server setup with stdio transport
• Tools Registry: src/tools/tools.ts - Centralized tool exports
• HTTP Client: src/utils.ts - Marvel API authentication and request handling
• Schema Definitions: src/tools/schemas.ts - Shared Zod schemas for Marvel API responses

Tool Pattern

Each tool follows a consistent structure in src/tools/{tool_name}/:

get_characters/
├── index.ts      # Tool definition with handler
└── schemas.ts    # Input validation schema

Tool implementation pattern:

export const get_characters = {
    description: `Fetch Marvel characters with optional filters.`,
    schema: GetCharactersSchema,
    handler: async (args: any) => {
        const argsParsed = GetCharactersSchema.parse(args);
        const res = await httpRequest('/characters', serializeQueryParams(argsParsed));
        return CharacterDataWrapperSchema.parse(res);
    }
};

Development Workflows

Build and Test

npm run build          # TypeScript compilation to dist/
npm run watch          # Watch mode compilation
npm run dev            # Build + watch with nodemon
npm run inspect        # Test with MCP Inspector

Local Development

• Use npm run inspect to test tools with MCP Inspector web interface
• Environment variables loaded from .env file (copy from .env.template)
• Server runs in stdio mode for MCP hosts or HTTP mode for direct testing

Adding New Tools

1. Create tool directory: src/tools/new_tool/
2. Define input schema in schemas.ts using Zod
3. Implement tool in index.ts following the pattern above
4. Export from src/tools/tools.ts
5. Update response schemas in src/tools/schemas.ts if needed