Secop MCP Project

SECOP II MCP Server

Servidor MCP (Model Context Protocol) para consultar el API de SECOP II de forma inteligente usando Claude y otros agentes de IA

Tabla de Contenidos

• ¿Qué es esto?
• Problema que resuelve
• Características
• Requisitos
• Instalación
• Configuración
• Uso
• Tools Disponibles
• Resources Disponibles
• Ejemplos
• Arquitectura
• Desarrollo
• Testing
• Limitaciones
• Roadmap
• Documentación Adicional
• Licencia

¿Qué es esto?

Un servidor Model Context Protocol (MCP) que permite a Claude y otros agentes de IA consultar el sistema de contratación pública colombiano SECOP II en lenguaje natural.

En lugar de:

curl "https://www.datos.gov.co/resource/p6dx-8zbt.json?$where=entidad LIKE '%MINISTERIO%' AND departamento_entidad='Bogotá D.C.'&$limit=50"

Ahora puedes:

Usuario: "Busca licitaciones activas de servicios TI en Bogotá publicadas este mes"
Claude: [Usa el servidor MCP automáticamente y retorna resultados estructurados]

Problema que resuelve

Las empresas que contratan con el sector público colombiano necesitan:

• Encontrar oportunidades de contratación activas
• Investigar procesos históricos similares
• Analizar requisitos y modalidades de contratación
• Identificar entidades que contratan servicios específicos

Actualmente esto requiere:

• L Búsquedas manuales en datos.gov.co
• L Conocimiento técnico del API Socrata y lenguaje SoQL
• L Construcción manual de queries complejas
• L Procesamiento de respuestas JSON grandes

Con este servidor MCP:

• Consultas en lenguaje natural vía Claude
• Acceso programático simple
• Filtros inteligentes automáticos
• Respuestas estructuradas y fáciles de procesar

Características

MVP v1.0

• 3 Tools principales para búsqueda y análisis:

- search_processes - Búsqueda flexible con 12 parámetros - get_process_details - Detalles completos de un proceso - aggregate_by_entity - Estadísticas por entidad

• 1 Resource:

- secop://data-dictionary - Diccionario de datos completo (59 campos)

• Características técnicas:

- Autenticación segura con Socrata API - Retry automático con exponential backoff - Manejo robusto de errores - Validación de schemas con Zod - TypeScript strict mode

Requisitos

• Node.js 20 o superior
• npm o yarn
• Credenciales de Socrata API (ver Configuración)
• Claude Code o cualquier cliente MCP compatible

Instalación

Opción 1: Desde el repositorio

# Clonar el repositorio
git clone https://github.com/tu-usuario/secop-scrapper.git
cd secop-scrapper

# Instalar dependencias
npm install

# Compilar TypeScript
npm run build

Opción 2: Desarrollo local

# Instalar en modo desarrollo
npm install

# Ejecutar en modo watch
npm run dev

Configuración

1. Variables de entorno

Crear archivo .env en la raíz del proyecto:

# Credenciales Socrata (REQUERIDO)
SOCRATA_API_KEY=tu_api_key_aquí
SOCRATA_API_SECRET=tu_api_secret_aquí
SOCRATA_APP_TOKEN=tu_app_token_aquí

# Configuración opcional (valores por defecto)
SOCRATA_BASE_URL=https://www.datos.gov.co
SOCRATA_DATASET_ID=p6dx-8zbt
REQUEST_TIMEOUT_MS=30000
MAX_RESULTS_LIMIT=200
RETRY_ATTEMPTS=3

2. Obtener credenciales de Socrata

Ver documentación en docs/secop-api-settings.md para instrucciones detalladas sobre cómo obtener:

• API Key
• API Secret
• App Token

3. Configurar en Claude Code

Añadir al archivo de configuración de MCP servers:

En Linux/macOS: ~/.config/claude-code/mcp.json En Windows: %APPDATA%\claude-code\mcp.json

{
  "mcpServers": {
    "secop": {
      "command": "node",
      "args": ["/ruta/completa/al/proyecto/dist/index.js"],
      "env": {
        "SOCRATA_API_KEY": "tu_api_key",
        "SOCRATA_API_SECRET": "tu_api_secret",
        "SOCRATA_APP_TOKEN": "tu_app_token"
      }
    }
  }
}

Nota: También puedes usar las credenciales que están documentadas en docs/secop-api-settings.md si tienes acceso al repositorio.

Uso

En Claude Code

Una vez configurado, simplemente pregunta en lenguaje natural:

Encuentra licitaciones activas de consultoría en Bogotá

Muéstrame qué ha contratado el Ministerio de Salud en 2024

¿Qué modalidad de contratación usa más la Alcaldía de Medellín?

Dame detalles del proceso OCDS-87SD3T-...

Claude usará automáticamente los tools del servidor MCP para responder.

Verificar que funciona

# Desde Claude Code
> ¿Está funcionando el servidor SECOP?

# Claude intentará usar el servidor y te dirá si está conectado

Tools Disponibles

1. search_processes

Búsqueda flexible de procesos de contratación.

Parámetros disponibles:

• entity_name (string) - Nombre de la entidad (búsqueda parcial)
• department (string) - Departamento (ej: "Bogotá D.C.")
• city (string) - Ciudad
• phase (enum) - Fase del proceso: Planeación, Selección, Evaluación, Adjudicación, Contratación, Ejecución
• modality (string) - Modalidad: Licitación Pública, Selección Abreviada, Concurso de Méritos, etc.
• min_value (number) - Valor mínimo en COP
• max_value (number) - Valor máximo en COP
• from_date (string) - Fecha inicial (YYYY-MM-DD)
• to_date (string) - Fecha final (YYYY-MM-DD)
• status (string) - Estado: Activo, Adjudicado, Desierto, Celebrado
• limit (number) - Máximo de resultados (1-200, default: 50)

Ejemplo de respuesta:

{
  "total_found": 1234,
  "returned": 50,
  "processes": [
    {
      "id": "OCDS-87SD3T-...",
      "reference": "CD-001-2024",
      "entity": "MINISTERIO DE SALUD",
      "title": "Adquisición de equipos médicos",
      "phase": "Selección",
      "status": "Activo",
      "modality": "Licitación Pública",
      "base_value": 500000000,
      "publication_date": "2024-11-01T10:30:00Z",
      "deadline": "2024-12-15T17:00:00Z",
      "url": "https://www.colombiacompra.gov.co/proceso/..."
    }
  ]
}

2. get_process_details

Obtener información detallada de un proceso específico.

Parámetros:

• process_id (string, requerido) - ID del proceso (OCDS o referencia)

Ejemplo de respuesta:

{
  "process": {
    "basic_info": { "id": "...", "reference": "...", "title": "..." },
    "entity": { "name": "...", "nit": "...", "department": "..." },
    "procurement": { "phase": "...", "modality": "...", "base_value": 0 },
    "dates": { "publication": "...", "deadline": "..." },
    "statistics": { "views": 0, "interested_providers": 0 },
    "award": { "is_awarded": false, "provider_name": null }
  }
}

3. aggregate_by_entity

Estadísticas agregadas de contratación por entidad.

Parámetros:

• entity_nit (string, requerido) - NIT de la entidad
• from_date (string, opcional) - Fecha inicial
• to_date (string, opcional) - Fecha final

Ejemplo de respuesta:

{
  "entity": { "name": "...", "nit": "..." },
  "statistics": {
    "total_processes": 150,
    "total_value": 15000000000,
    "by_phase": { "Selección": 50, "Adjudicación": 80 },
    "by_modality": { "Licitación Pública": 30 },
    "top_categories": [
      { "code": "80111500", "name": "Servicios de Consultoría", "count": 45 }
    ]
  }
}

Resources Disponibles

secop://data-dictionary

Diccionario de datos completo del dataset SECOP II.

Contiene:

• 59 campos con descripciones
• Tipos de datos
• Ejemplos de valores
• Mapeo entre nombres de columna y API fields

Uso:

> Muéstrame el diccionario de datos de SECOP II

Ejemplos

Caso 1: Encontrar oportunidades activas

Pregunta:

Muéstrame licitaciones activas de servicios TI en Bogotá con valor mayor a $100 millones

Claude ejecutará:

search_processes({
  status: "Activo",
  department: "Bogotá D.C.",
  min_value: 100000000
})

Caso 2: Investigar entidad específica

Pregunta:

¿Qué ha contratado el Ministerio de Salud este año?

Claude ejecutará:

aggregate_by_entity({
  entity_nit: "800123456", // Claude busca el NIT primero
  from_date: "2024-01-01",
  to_date: "2024-12-31"
})

Caso 3: Analizar modalidad

Pregunta:

¿Qué procesos de selección abreviada se publicaron esta semana?

Claude ejecutará:

search_processes({
  modality: "Selección Abreviada",
  from_date: "2024-11-19", // Hace 7 días
  to_date: "2024-11-26"
})

Arquitectura

Diagrama de componentes

      +------------------------+
      | MCP Host (Claude Code) |
      +------------------------+
                  ^
                  | STDIO
                  v
      +----------------------------------+
      |        MCP Server (secop)        |
      |                                  |
      |  +----------------------------+  |
      |  |       Tools Handler        |  |
      |  |  - search_processes        |  |
      |  |  - get_process_details     |  |
      |  |  - aggregate_by_entity     |  |
      |  +----------------------------+  |
      |                |                 |
      |                v                 |
      |  +----------------------------+  |
      |  |     Socrata API Client     |  |
      |  |  - Auth & Retry Logic      |  |
      |  |  - SoQL Query Builder      |  |
      |  +----------------------------+  |
      +----------------------------------+
                  |
                  | HTTPS
                  v
      +----------------------------------+
      |           Socrata API            |
      |  Dataset: p6dx-8zbt (SECOP II)   |
      +----------------------------------+

Estructura del proyecto

secop-scrapper/
├── src/
│   ├── index.ts              # Entry point, MCP server
│   ├── config.ts             # Configuration management
│   ├── tools/
│   │   ├── search.ts         # search_processes
│   │   ├── details.ts        # get_process_details
│   │   └── aggregate.ts      # aggregate_by_entity
│   ├── resources/
│   │   └── dictionary.ts     # data-dictionary resource
│   ├── api/
│   │   ├── client.ts         # Socrata API client
│   │   ├── queries.ts        # SoQL query builder
│   │   ├── types.ts          # TypeScript interfaces
│   │   └── utils.ts          # Utilities
│   └── utils.ts
├── tests/
│   └── *.test.ts             # Unit & integration tests
├── data/
│   └── data-dictionary.json  # Static data dictionary
├── docs/
│   ├── SECOP I y II_ Investigación Exhaustiva.md
│   ├── diccionariodedatos-secop-ii-procesos-de-contrataciondocx.md
│   ├── secop-api-settings.md
│   └── secop-ii-procesos-de-contratacion-estadisticas-nacionales.md
├── SPECIFICATION.md          # MVP Specification (590 líneas)
├── PLAN.md                   # Technical Plan (966 líneas)
├── TASKS.md                  # Implementation Tasks (982 líneas)
├── .env.example
├── .gitignore
├── package.json
├── tsconfig.json
├── vitest.config.ts
└── README.md

Desarrollo

Setup inicial

# Instalar dependencias
npm install

# Compilar TypeScript
npm run build

# Modo desarrollo (watch)
npm run dev

Scripts disponibles

npm run dev              # Desarrollo con hot reload
npm run build            # Compilar TypeScript
npm run start            # Ejecutar servidor compilado
npm test                 # Ejecutar tests
npm run test:watch       # Tests en modo watch
npm run test:coverage    # Coverage report
npm run lint             # Linting
npm run type-check       # Type checking sin compilar

Stack tecnológico

• Lenguaje: TypeScript 5.6+
• Runtime: Node.js 20+
• MCP SDK: @modelcontextprotocol/sdk v1.0
• HTTP Client: axios v1.7
• Validación: zod v3.23
• Testing: vitest v2.1
• Build: tsx v4.19

Testing

Ejecutar tests

# Todos los tests
npm test

# Tests en modo watch
npm run test:watch

# Coverage
npm run test:coverage

Niveles de testing

Unit Tests:

• Validación de configuración
• Query builder (SoQL)
• Transformación de errores
• Transformación de respuestas

Integration Tests:

• API client con mocks
• Tools end-to-end
• Resources end-to-end

Manual Tests:

• Integración con Claude Code
• Casos de uso reales

Objetivo de cobertura

• Unit tests: 80%+
• Integration tests: 100% de tools y resources

Limitaciones

Limitaciones conocidas (MVP v1.0)

1. Sin caché: Cada consulta golpea el API (puede ser lento)
2. Sin paginación inteligente: Máximo 200 resultados por query
3. Sin búsqueda por texto completo: Solo filtros exactos o LIKE simple
4. Sin análisis de documentos: No lee PDFs de términos de referencia
5. Solo SECOP II: No incluye SECOP I (legacy system)
6. Sin persistencia: No guarda historial de consultas
7. Transport único: Solo STDIO, no HTTP/SSE

Rate limiting de Socrata

• Con App Token: ~1000 requests/hora
• Sin App Token: ~100 requests/hora (no recomendado)
• El servidor implementa retry automático con exponential backoff

Roadmap

v1.1 (Próxima versión)

• [ ] Caché en memoria con TTL
• [ ] Tool adicional: search_by_unspsc (búsqueda por categoría UNSPSC)
• [ ] Mejoras en parseo de fechas y valores monetarios
• [ ] Paginación automática para resultados > 200

v1.2

• [ ] Prompt especializado para análisis de competencia
• [ ] Tool: compare_processes (comparar múltiples procesos)
• [ ] Resource adicional: estadísticas generales del dataset
• [ ] Soporte para filtros UNSPSC más inteligentes

v2.0

• [ ] Soporte para HTTP/SSE transport
• [ ] Integración con SECOP I
• [ ] Sistema de alertas (requiere persistencia)
• [ ] Dashboard o UI opcional

Documentación Adicional

Documentos de especificación

• SPECIFICATION.md - Especificación completa del MVP (590 líneas)
• PLAN.md - Plan técnico de implementación (966 líneas)
• TASKS.md - Tareas de implementación por fases (982 líneas)

Documentación de investigación

• SECOP I y II: Investigación Exhaustiva - Comparación entre sistemas
• Diccionario de Datos - 59 campos del dataset
• Configuración API - Cómo obtener credenciales
• Estadísticas Nacionales - Overview del dataset

Referencias externas

• Model Context Protocol - Especificación oficial
• MCP Best Practices - Guía de arquitectura
• Socrata API Docs - Documentación del API
• SECOP II Dataset - Datos abiertos
• Spec-Driven Development - Metodología

Manejo de Errores

El servidor categoriza errores en 5 tipos:

1. VALIDATION_ERROR (400)

Parámetros inválidos o malformados

{
  "error": "VALIDATION_ERROR",
  "message": "El parámetro 'from_date' debe tener formato YYYY-MM-DD"
}

2. API_ERROR (502)

Error al consultar API de Socrata

{
  "error": "API_ERROR",
  "message": "Error al consultar API de Socrata",
  "details": { "status": 500 }
}

3. AUTH_ERROR (401)

Credenciales inválidas o expiradas

{
  "error": "AUTH_ERROR",
  "message": "Credenciales de API inválidas o expiradas"
}

4. RATE_LIMIT_ERROR (429)

Límite de requests excedido

{
  "error": "RATE_LIMIT_ERROR",
  "message": "Límite de requests excedido. Intente nuevamente en 60 segundos",
  "retry_after": 60
}

5. TIMEOUT_ERROR (504)

Query tardó más de 30 segundos

{
  "error": "TIMEOUT_ERROR",
  "message": "La consulta tardó más de 30 segundos. Intente con filtros más específicos"
}

Contribuir

Este proyecto está en fase MVP. Las contribuciones son bienvenidas una vez se complete la implementación inicial.

Proceso de desarrollo

1. Fase actual: PLAN (Planning/Specification)
2. Metodología: Spec-Driven Development
3. Siguiente paso: Implementación de Phase 1 (Setup & Infrastructure)

Ver TASKS.md para el plan de implementación completo.

Documentación de Referencia y Mejores Prácticas

Esta sección recopila las mejores prácticas y documentación clave para el desarrollo de servidores MCP y el uso de IA en el ciclo de vida del desarrollo, basándose en la documentación oficial del protocolo y el blog de Anthropic.

1. Ecosistema MCP (Model Context Protocol)

Repositorios Oficiales y Servidores de Referencia:

• modelcontextprotocol/servers: Colección oficial de servidores de referencia. Incluye implementaciones para:

* filesystem: Acceso seguro a archivos. * git: Lectura y manipulación de repositorios. * memory: Grafo de conocimiento persistente. * sequential-thinking: Herramienta para resolución de problemas complejos.

• Integraciones de Referencia: Servidores pre-construidos para Google Drive, Slack, GitHub y Postgres.
• SDKs Disponibles: TypeScript, Python, Java, Go, Kotlin, entre otros.

Mejores Prácticas de Seguridad y Performance:

• Seguridad:

* OAuth 2.1: Estándar obligatorio para autenticación en transportes HTTP. * Sandboxing: Ejecutar servidores con privilegios mínimos (nunca root). * Human-in-the-loop: Requerir aprobación humana para acciones de alto riesgo (escritura, ejecución).

• Performance:

* Code Execution vs Granular Tools: En lugar de muchas tools pequeñas, exponer un entorno de ejecución seguro (sandbox) permite al modelo filtrar y procesar datos en un solo paso, reduciendo latencia y tokens. * Tool Search: Permitir al modelo buscar tools bajo demanda en lugar de cargar todas las definiciones en el contexto.

2. Spec-Driven Development (SDD) - Metodología

El desarrollo guiado por especificaciones (SDD) pone a la especificación como la fuente de verdad, permitiendo que los agentes de IA generen código de alta calidad y alineado con los objetivos.

Workflow Recomendado:

1. Specify (Especificar): Definir el "qué" y el "por qué". Crear una especificación detallada centrada en la experiencia de usuario y objetivos.
2. Plan (Planificar): Definir el "cómo". Crear un plan técnico que respete la arquitectura y restricciones del proyecto.
3. Tasks (Tareas): Desglosar el plan en tareas pequeñas, atómicas y verificables.
4. Implement (Implementar): Ejecución asistida por IA, siguiendo estrictamente las tareas definidas.

Tips para el Éxito:

• Treat Specs as Code: Las especificaciones deben estar en el repositorio, versionadas y revisadas en Pull Requests.
• Human in the Loop: El desarrollador actúa como arquitecto y verificador. Nunca se debe aceptar código generado sin revisión crítica.
• Start Small: No intentar generar todo el proyecto de una vez. Iterar por módulos o funcionalidades pequeñas.

Referencias Oficiales:

• MCP Documentation & Architecture
• MCP Servers Repository
• Anthropic News & Announcements

Licencia

Todos los derechos reservados @oddradiocircle 2025

Soporte

Para reportar bugs o solicitar features:

• Abrir un issue en GitHub
• Consultar la documentación en docs/
• Revisar SPECIFICATION.md para entender el alcance del MVP

Estado del Proyecto

  Estado: PLANNING                                       
  Versión: MVP 1.0 (en desarrollo)                       
  Última actualización: 2025-12-13                       

Fases completadas:

• Investigación (SECOP I/II)
• Especificación (SPECIFICATION.md)
• Planificación técnica (PLAN.md)
• Definición de tareas (TASKS.md)
• README y documentación

Próxima fase:

• 🚀 Phase 1: Setup & Infrastructure (ver TASKS.md)