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

![TypeScript](https://www.typescriptlang.org/) ](https://nodejs.org/) ![MCP](https://modelcontextprotocol.io/)

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)

Sin caché: Cada consulta golpea el API (puede ser lento)
Sin paginación inteligente: Máximo 200 resultados por query
Sin búsqueda por texto completo: Solo filtros exactos o LIKE simple
Sin análisis de documentos: No lee PDFs de términos de referencia
Solo SECOP II: No incluye SECOP I (legacy system)
Sin persistencia: No guarda historial de consultas
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

Fase actual: PLAN (Planning/Specification)
Metodología: Spec-Driven Development
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:

Specify (Especificar): Definir el "qué" y el "por qué". Crear una especificación detallada centrada en la experiencia de usuario y objetivos.
Plan (Planificar): Definir el "cómo". Crear un plan técnico que respete la arquitectura y restricciones del proyecto.
Tasks (Tareas): Desglosar el plan en tareas pequeñas, atómicas y verificables.
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:

Licencia

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)

Secop MCP Project

快速接入

详细介绍

SECOP II MCP Server

Tabla de Contenidos

¿Qué es esto?

Problema que resuelve

Características

MVP v1.0

Requisitos

Instalación

Opción 1: Desde el repositorio

Opción 2: Desarrollo local

Configuración

1. Variables de entorno

2. Obtener credenciales de Socrata

3. Configurar en Claude Code

Uso

En Claude Code

Verificar que funciona

Tools Disponibles

1. search_processes

2. get_process_details

3. aggregate_by_entity

Resources Disponibles

secop://data-dictionary

Ejemplos

Caso 1: Encontrar oportunidades activas

Caso 2: Investigar entidad específica

Caso 3: Analizar modalidad

Arquitectura

Diagrama de componentes

Estructura del proyecto

Desarrollo

Setup inicial

Scripts disponibles

Stack tecnológico

Testing

Ejecutar tests

Niveles de testing

Objetivo de cobertura

Limitaciones

Limitaciones conocidas (MVP v1.0)

Rate limiting de Socrata

Roadmap

v1.1 (Próxima versión)

v1.2

v2.0

Documentación Adicional

Documentos de especificación

Documentación de investigación

Referencias externas

Manejo de Errores

1. VALIDATION_ERROR (400)

2. API_ERROR (502)

3. AUTH_ERROR (401)

4. RATE_LIMIT_ERROR (429)

5. TIMEOUT_ERROR (504)

Contribuir

Proceso de desarrollo

Documentación de Referencia y Mejores Prácticas

1. Ecosistema MCP (Model Context Protocol)

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

Licencia

Soporte

Estado del Proyecto

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

1. `search_processes`

2. `get_process_details`

3. `aggregate_by_entity`

`secop://data-dictionary`