foaas-mcp: Instructions file for GitHub Copilot

GitHub Copilot Instructions for FOAAS MCP

🚨 CRITICAL: Code Review Guidelines (READ FIRST)

Before suggesting improvements in PR reviews:

1. ✅ Check docs/roadmap/backlog/ - Is it already planned?
2. ✅ Check docs/roadmap/next/ - Is it in progress?
3. ❌ Don't suggest improvements already documented in the roadmap

Example: Don't flag "CI is too complex" - it's tracked in build-script-externalization.md

Why? Keep reviews focused on current PR quality, not rehashing known future work.

---

Project Overview

MCP server exposing FOAAS (Fuck Off As A Service) via Docker. Uses stdio transport for VS Code integration.

⚠️ Content Warning: Intentionally contains explicit language.

Architecture

Transport: stdio only (no HTTP) - simpler, more secure, sufficient for VS Code demo
Runtime: Docker (Debian 12 Bookworm Slim + Node.js 20.19.5 + dumb-init)
Language: TypeScript 5.9.3 (ES2022 modules, strict mode)
Tools: 23 individual tools (all foaas_* prefix, direct 1:1 API mapping)

Tool Design Pattern

Individual tools only (foaas_*): Direct 1:1 mapping to FOAAS API operations

• Example: foaas_legend → GET /legend/{name}/{from}
• Example: foaas_logs → GET /logs/{from}
• Direct, predictable, AI picks best contextual fit
• No randomization - precise control over responses

Why individual tools only?

• Consistent parameters within each tool
• AI can select the perfect response for context
• Simpler architecture (1 tool = 1 operation)
• Better demo of MCP's smart tool selection
• Removed group tools due to parameter inconsistency

Key Files

• src/server.ts - MCP server setup, tool registration (import → array → register)
• src/foaas/client.ts - FOAAS API client (all operations, URL encoding, error handling)
• src/tools/shared/schemas.ts - Shared Zod schemas (fromParam, toParam, formatFoaasResponse)
• src/tools/individual/*.ts - Individual tool implementations (1 file = 1 tool)