How traves-theberge/mikmaq-dictionary-api-and-mcp works
Project type and purpose
• This is a backend-only, microservices-style application comprising two primary services:
• The Mi’kmaq Dictionary RESTful API (Express.js, TypeScript)
• The MCP (Model Context Protocol) server for IDE/AI integration (also TypeScript/Express)
• Purpose: serve in-memory Mi’kmaq↔English dictionary lookups and expose a JSON-RPC interface for AI/IDE assistants.
File structure
• Top-level “src/” implements the Dictionary API:
• controllers/ → HTTP handlers
• services/ → business logic & in-memory dictionary loading (dictionary.json)
• routes/ → Express route definitions
• middleware/ → CORS, rate limiting, security headers, error handling
• “Mcp/” subfolder: a separate Node service implementing the JSON-RPC MCP server:
• index.ts → MCP server entry point
• dictionary-client.ts → HTTP client wrapper calling the Dictionary API
• Configuration & orchestration: Dockerfile(s), docker-compose.yml, tsconfig.json, jest.config.js.
• Test suites under “tests/” validate controllers, services, integration flows.
Key insights from README
• Two Docker Compose services share a user-defined network:
• mikmaq-dictionary-api: port 3000, serves HTTP REST API
• mcp-mikmaq-mcp-server: MCP JSON-RPC endpoints for IDE tooling
• Core data store is a read-only dictionary.json loaded into memory for sub-ms lookups.
• Standard layered architecture (routing → controllers → services → data).
1. Client(s):
– AI Assistant / IDE (via MCP JSON-RPC)
– External Applications / CLI / Browser (HTTP REST)
2. Docker Compose Network
3. Service: Dictionary API
– Express Middleware (security, CORS, rate limiter)
– Router → Controllers → DictionaryService
– In-memory Data Store (dictionary.json)
4. Service: MCP Server
– JSON-RPC Endpoint
– dictionary-client.ts (HTTP client) → calls Dictionary API
5. Data Artifact: dictionary.json (volume mount/read-only)
– External Client → HTTP REST → Dictionary API
– MCP Server → HTTP Client → Dictionary API
– Dictionary API loads dictionary.json at startup into in-memory index
– IDE/AI ↔ JSON-RPC ↔ MCP Server
– Docker Compose orchestrates TCP/network connectivity
c. Architectural patterns and design principles:
– Layered MVC-style within each service (routes/controllers/services)
– Single responsibility: API handles REST, MCP handles RPC
– In-memory indexing for ultra-fast lookups (no external DB)
– Containerized microservices connected by a Docker network
– Test suites enforce 100% coverage of core logic
d. Relevant technologies:
– Node.js, TypeScript, Express.js
– Docker, Docker Compose
– JSON-RPC for MCP
– Jest for testing
Final recommendations
• Drill down into the API container to expose the layered structure.
• Optionally, include a small inset showing test suites hooking into services for continuous integration.