Skip to main content
Glama

ApiColombiaMCP

by esneyder
GitHub
TypeScript
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

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.

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)

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)

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:

export const TOOL_NAMES = { GET_COUNTRY: 'getCountry', NEW_TOOL: 'newTool', // Add your new tool name } as const;

  1. Create service in services/ directory:

// services/new-tool.service.ts export async function newToolService(): Promise<ApiColombiaResponse> { // Your implementation }

  1. Add tool configuration in tools/index.ts:

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:

# .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+):

corepack enable

  1. Install pnpm (if not available):

npm install -g pnpm

  1. Verify pnpm version:

pnpm --version

Installation

# 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!

Deploy Server
-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Tools

Provides comprehensive information about Colombia including departments, regions, cities, tourist attractions, and general country data through the API Colombia service. Enables users to query Colombian geographical and administrative information through natural language.

  1. 📊 Data Source
    1. 🏗️ Architecture Overview
      1. 📁 Project Structure
    2. 🎯 Architecture Layers
      1. 1. Presentation Layer (index.ts)
      2. 2. Tools Layer (tools/)
      3. 3. Business Logic Layer (services/)
      4. 4. Shared Layer (shared/)
    3. 🔧 Key Components
      1. Constants (shared/constants/index.ts)
      2. Tool Configuration (tools/index.ts)
      3. Service Implementation (services/country.services.ts)
    4. 🚀 Adding New Tools
      1. 🔒 Environment Configuration
        1. 🧪 Development
          1. Prerequisites
          2. Package Manager Setup
          3. Installation
          4. Troubleshooting Package Manager Issues
        2. 📋 Features
          1. 🔧 Technologies Used
            1. 🎯 Benefits of This Architecture

              New MCP Servers

              MCP directory API

              We provide all the information about MCP servers via our MCP API.

              curl -X GET 'https://glama.ai/api/mcp/v1/servers/esneyder/apicolombia-mcp'

              If you have feedback or need assistance with the MCP directory API, please join our Discord server