Memory-Alpha-MCP copilot-instructions.md

Project Overview

Memory Alpha MCP is a TypeScript/ESM MCP server that provides Star Trek knowledge from the Memory Alpha MediaWiki API. It parses wikitext at runtime and exposes it through MCP tools, prompts, and resources. The server communicates over stdio — treat transport safety as a core constraint.

Primary stack: Node.js 18+, TypeScript (NodeNext ESM), @modelcontextprotocol/sdk, wtf_wikipedia, zod, vitest, @vitest/coverage-v8.

Repository Map

• src/index.ts — MCP server bootstrap, stdio transport, graceful shutdown, tool/prompt/resource registration
• src/api/client.ts — owns all HTTP: rate limiting (~5 req/s), 10s timeout, 1 retry, in-memory caching
• src/api/ — MediaWiki API helpers (search, article, categories, episodes, random)
• src/parser/wikitext.ts — primary wikitext-to-text pipeline; disambiguation detection
• src/parser/infobox.ts — infobox/sidebar extraction; fallback for nested {{sidebar ...}} templates
• src/parser/sections.ts — section extraction
• src/tools/ — 26 MCP tools: alien-phrases, article, away-team, battle-simulator, categories, character, compare, crew-manifest, episode, episode-recommender, holodeck, list-episodes, on-this-day, prime-directive, random, red-shirt, rules-of-acquisition, search, species, stardate, starship, timeline, trivia, who-said-it, + more
• src/prompts/index.ts — Trek-themed MCP prompt registrations
• src/resources/index.ts — static MCP resources under trek://... URIs
• src/utils/attribution.ts — withAttribution() wrapper
• src/utils/logger.ts — safe logging via console.error
• src/utils/cache.ts, shuffle.ts, text.ts — shared helpers
• tests/ — Vitest unit tests

Commands

Run from the repository root:

npm install          # install dependencies
npm run build        # tsc compile src/ → dist/
npm run dev          # run server with tsx src/index.ts
npm test             # run vitest suite
npx @modelcontextprotocol/inspector node dist/index.js  # interactive MCP inspector