ApiColombiaMCP

# ApiColombiaMCP A Model Context Protocol (MCP) server that provides information about Colombia through the API Colombia service. ## 📊 Data Source This project uses the **API Colombia** service for educational and practical purposes. The API provides comprehensive information about Colombia including departments, regions, cities, and general country data. - **API URL**: https://api-colombia.com/ - **Documentation**: https://api-colombia.com/#informacionAPIS - **Purpose**: Educational and practical implementation of MCP server - **Data Coverage**: Departments, regions, cities, tourist attractions, and general country information > **Note**: This implementation is for educational and practical purposes only. The API Colombia service is a public, open-source project that provides free access to Colombian data. ## 🏗️ Architecture Overview This project follows **Clean Architecture** principles with a modular, scalable structure designed for maintainability and extensibility. ### 📁 Project Structure ``` ApiColombiaMCP/ ├── src/ │ ├── index.ts # Main server entry point │ ├── services/ # Business logic layer │ │ └── country.services.ts # Country data operations │ ├── tools/ # Tool definitions layer │ │ └── index.ts # MCP tool configurations │ └── shared/ # Shared utilities layer │ ├── constants/ # Centralized constants │ │ └── index.ts # Tool names, descriptions, config │ ├── types/ # Type definitions │ │ └── response.mcp.ts # MCP response types │ └── index.ts # Shared exports ├── .env # Environment variables ├── package.json # Dependencies and scripts └── tsconfig.json # TypeScript configuration ``` ## 🎯 Architecture Layers ### 1. **Presentation Layer** (`index.ts`) - **Responsibility**: Server initialization and tool registration - **Key Features**: - Uses constants for configuration - Dynamic tool registration from centralized configuration - Clean separation from business logic ### 2. **Tools Layer** (`tools/`) - **Responsibility**: MCP tool definitions and configurations - **Key Features**: - Centralized tool configuration - Interface-based tool definitions - Easy extension for new tools - Type-safe tool registration ### 3. **Business Logic Layer** (`services/`) - **Responsibility**: Core business operations - **Key Features**: - External API integration - Data transformation and formatting - Error handling and validation - Environment-based configuration ### 4. **Shared Layer** (`shared/`) - **Responsibility**: Cross-cutting concerns and utilities - **Key Features**: - Centralized constants and configuration - Shared type definitions - Error message standardization - Reusable utilities ## 🔧 Key Components ### Constants (`shared/constants/index.ts`) ```typescript export const TOOL_NAMES = { GET_COUNTRY: 'getCountry', } as const; export const TOOL_DESCRIPTIONS = { GET_COUNTRY: 'Get information about a country', } as const; ``` ### Tool Configuration (`tools/index.ts`) ```typescript export interface ToolConfig { name: string; description: string; handler: () => Promise<ApiColombiaResponse>; } export const tools: ToolConfig[] = [ { name: TOOL_NAMES.GET_COUNTRY, description: TOOL_DESCRIPTIONS.GET_COUNTRY, handler: getCountry, }, ]; ``` ### Service Implementation (`services/country.services.ts`) - Fetches data from API Colombia - Formats response for MCP compatibility - Handles errors gracefully - Uses environment variables for configuration ## 🚀 Adding New Tools To add a new tool, follow these steps: 1. **Add constants** in `shared/constants/index.ts`: ```typescript export const TOOL_NAMES = { GET_COUNTRY: 'getCountry', NEW_TOOL: 'newTool', // Add your new tool name } as const; ``` 2. **Create service** in `services/` directory: ```typescript // services/new-tool.service.ts export async function newToolService(): Promise<ApiColombiaResponse> { // Your implementation } ``` 3. **Add tool configuration** in `tools/index.ts`: ```typescript export const tools: ToolConfig[] = [ { name: TOOL_NAMES.GET_COUNTRY, description: TOOL_DESCRIPTIONS.GET_COUNTRY, handler: getCountry, }, { name: TOOL_NAMES.NEW_TOOL, description: TOOL_DESCRIPTIONS.NEW_TOOL, handler: newToolService, }, ]; ``` ## 🔒 Environment Configuration The project uses environment variables for configuration: ```bash # .env API_COLOMBIA_URL=https://api-colombia.com/api/ ``` The service gracefully falls back to default URLs if environment variables are not set. ## 🧪 Development ### Prerequisites - Node.js (v16.9+ or v14.19+) - pnpm (package manager) ### Package Manager Setup This project uses **pnpm** as the package manager. If you encounter package manager conflicts: 1. **Enable Corepack** (included with Node.js 16.9+): ```bash corepack enable ``` 2. **Install pnpm** (if not available): ```bash npm install -g pnpm ``` 3. **Verify pnpm version**: ```bash pnpm --version ``` ### Installation ```bash # Install dependencies pnpm install # Build the project pnpm build # Run the MCP server node build/index.js ``` ### Troubleshooting Package Manager Issues If you see package manager errors: - Ensure Corepack is enabled: `corepack enable` - Clear npm cache: `npm cache clean --force` - Use pnpm directly instead of npm/yarn - Check that `.npmrc` file exists in the project root ## 📋 Features - **Country Information**: Get comprehensive data about Colombia - **Clean Architecture**: Modular, testable, and maintainable code - **Type Safety**: Full TypeScript support - **Error Handling**: Graceful error management - **Environment Configuration**: Flexible configuration management - **Scalable Design**: Easy to extend with new tools ## 🔧 Technologies Used - **TypeScript**: Type-safe JavaScript - **MCP SDK**: Model Context Protocol server development - **Zod**: Schema validation - **Node.js**: Runtime environment ## 🎯 Benefits of This Architecture - **🔄 Scalability**: Easy to add new tools and features - **📝 Maintainability**: Clear separation of concerns - **🧪 Testability**: Each layer can be tested independently - **📋 Type Safety**: Full TypeScript coverage - **🚀 Consistency**: Centralized configuration and constants - **🔧 Flexibility**: Environment-based configuration - **📖 Readability**: Clean, well-organized code structure This architecture ensures your MCP server is ready for production use and can grow with your needs!