chiclana-avisos-mcp (GECOR Avisos MCP)

Servidor Model Context Protocol (MCP) para gestionar avisos e incidencias municipales en Chiclana de la Frontera (Cádiz) y cualquier municipio soportado por la plataforma GECOR.

Inspirado en el diseño y patrones de seguridad de madrid-avisos-mcp.

Permite que un agente de IA pueda:

• Recibir una foto y dirección o referencia escrita, y extraer GPS EXIF cuando exista.

• Elegir categorías oficiales GECOR y aclarar dudas antes de actuar.

• Previsualizar un aviso sin enviarlo y registrarlo solo tras confirmación explícita del resumen exacto.

• Consultar incidencias previamente registradas y su estado.

📦 Instalación

Requiere Node.js 20 o superior. El paquete se publica en npm como chiclana-avisos-mcp y se ejecuta con npx, sin clonar el repositorio.

1. Obtener el token de GECOR

Autentica con GECOR y obtén el token de la sesión (por ejemplo, desde localStorage en DevTools de gecorweb.com, clave user → campo token). El servidor únicamente acepta GECOR_TOKEN en el entorno de su propio proceso MCP. No guarda sesiones ni admite inicio de sesión con email y contraseña.

2. Configurar en tu cliente MCP

Claude Desktop

Añade a claude_desktop_config.json:

{
  "mcpServers": {
    "chiclana-avisos": {
      "command": "npx",
      "args": ["-y", "chiclana-avisos-mcp"],
      "env": {
        "GECOR_TOKEN": "<tu-token-gecor>",
        "GECOR_AYTO_ID": "268"
      }
    }
  }
}

Claude Code

claude mcp add chiclana-avisos \
  -e GECOR_TOKEN=<tu-token-gecor> \
  -e GECOR_AYTO_ID=268 \
  -- npx -y chiclana-avisos-mcp

Otros clientes MCP (OpenCode, Hermes, etc.)

Cualquier cliente que lance servidores MCP por stdio necesita los mismos tres elementos: comando, argumentos y entorno.

• command: npx

• args: ["-y", "chiclana-avisos-mcp"]

• env: GECOR_TOKEN y GECOR_AYTO_ID (por defecto 268)

Consulta la documentación de tu cliente para el formato exacto del fichero de configuración.

Confirmar una previsualización envía un aviso real al ayuntamiento. Antes de enviar, el agente siempre te muestra el resumen y espera tu «sí».

Para agentes de IA

Si eres un agente configurando este servidor para un usuario:

1. Pide al usuario su token de GECOR (ver 1. Obtener el token de GECOR); no lo busques ni lo extraigas por tu cuenta.

2. Configura la entrada MCP con npx -y chiclana-avisos-mcp y el token en env de esa entrada. Chiclana es GECOR_AYTO_ID=268; para otro municipio, obtén su ID con list_ayuntamientos.

3. Reinicia el cliente y llama a whoami: confirma el municipio activo y que hay token configurado, pero no valida el token. Para comprobar que GECOR lo acepta, llama a list_my_avisos (solo lectura).

4. Sigue el flujo de skill/SKILL.md: previsualizar, mostrar el resumen y enviar solo tras confirmación explícita.

5. Confirmar envía un aviso real al ayuntamiento: llama al envío confirmado únicamente después de un «sí» explícito de la persona al resumen exacto mostrado. Nunca confirmes por inferencia, por silencio ni ante una respuesta ambigua.

Desde el código

git clone https://github.com/dfernandezdaw/chiclana-avisos-mcp.git
cd chiclana-avisos-mcp
npm install
npm run build

Y apunta tu cliente MCP a dist/index.js (por ejemplo, en claude_desktop_config.json):

{
  "mcpServers": {
    "chiclana-avisos": {
      "command": "node",
      "args": ["/ruta/absoluta/a/chiclana-avisos-mcp/dist/index.js"],
      "env": {
        "GECOR_AYTO_ID": "268",
        "GECOR_TOKEN": "<tu-token-gecor>"
      }
    }
  }
}

Configura el token directamente en env para cada entrada MCP que inicie este servidor. No uses una exportación global del token: así las credenciales quedan limitadas al proceso MCP correspondiente.

Related MCP server: valencia-avisos-mcp

⚙️ Configuración

Variables de entorno leídas por el proceso MCP:

🛠️ Herramientas MCP Disponibles

🔒 Seguridad y confirmación explícita

El flujo de envío requiere confirmación explícita; la previsualización por sí sola no crea ningún aviso ni sube la foto, pero confirmarla envía un aviso real al ayuntamiento:

1. Usa create_aviso_from_photo para ambas fases. Para previsualizar, envía los campos del aviso y una foto no vacía mediante image_path o image_base64, sin token ni campos de confirmación. Usa list_categories para identificar categorías. La herramienta procesa EXIF internamente durante la previsualización; no existe una herramienta independiente parse_photo_gps.

2. Muestra un resumen breve de categoría, descripción, dirección/referencia, foto y ubicación disponible. No incluyas peticionario, tokens, payload crudo ni identidad privada.

3. Espera un sí inequívoco al resumen exacto en la misma conversación. Ante cambios o respuesta ambigua, crea una previsualización nueva y vuelve a pedir confirmación.

4. Tras confirmar, llama al mismo tool solo con preview_token, confirm: true y human_confirmed: true. Haz esta llamada solo tras un «sí» explícito al resumen exacto. Si falla la validación o la subida de la foto, informa que el aviso NO se envió; nunca reintentes una escritura posiblemente completada.

5. estado: ENVIADO_EXITOSAMENTE en la respuesta wrapper de Chiclana indica que la llamada MCP/API tuvo éxito, no que ese sea el estado de tramitación municipal. Comunica únicamente lo que devolvió la API: informa un número oficial de ticket o estado de tramitación solo si aparece en resultado devuelto por GECOR o está verificado inequívocamente; no lo adivines.

La dirección textual no se geocodifica en este proyecto: resolve_location por nombre de calle solo devuelve el CalleID. Si la foto no aporta GPS EXIF, solicita coordenadas explícitas; nunca inventes ubicación. Prefiere la foto original para conservar EXIF. No se admite subida remota HTTP.

Fotos

• Formatos: solo JPEG o PNG, detectados por su contenido. HEIC no se admite: conviértela antes (en iPhone, Ajustes › Cámara › Formatos › «Más compatible»).

• Tamaño máximo: 20 MB (GECOR_MAX_PHOTO_BYTES).

• image_path debe estar dentro de los directorios permitidos (GECOR_PHOTO_DIRS; por defecto el temporal del sistema, ~/Downloads, ~/Pictures, ~/Desktop y ~/.hermes) y apuntar a un fichero regular. Si no, usa image_base64 (admite prefijo data:image/...;base64,).

• GPS: solo se lee el EXIF de JPEG. Los PNG, las fotos reenviadas por apps que eliminan metadatos (p. ej. Telegram, salvo envío como archivo) y las capturas no aportan coordenadas.

• Reducción: los JPEG cuyo lado mayor supera 2048 px se reducen a 2048 px (calidad 85) conservando los segmentos EXIF/XMP originales, incluida la orientación. Si la reducción no es posible, se sube el original y la previsualización lo indica en foto.aviso_reduccion. Los PNG se suben sin cambios.

• Miniatura: la previsualización devuelve al modelo una imagen JPEG de lado mayor ≤ 1024 px (calidad 80) sin EXIF ni GPS, con la orientación ya aplicada; los PNG de hasta 1 MB se devuelven tal cual y los mayores no tienen miniatura. La miniatura nunca se sube: GECOR recibe la copia de 2048 px con EXIF. Si no se puede generar, la previsualización continúa sin ella.

• La previsualización incluye foto con mime, original_bytes, upload_bytes, width, height, reducida, exif_conservado y miniatura (más aviso_miniatura si no se pudo generar).

Errores y reintentos

• Cada petición a GECOR expira tras GECOR_TIMEOUT_MS (20 s por defecto). Las consultas (get*) se reintentan una vez ante timeout, error de red o 5xx; las escrituras nunca se reintentan automáticamente.

• El preview_token se consume antes de cualquier efecto: un mismo token no puede crear dos avisos.

• Si falla la subida de la foto, no se crea ningún aviso; genera una nueva previsualización.

• Si la creación devuelve «Envío NO confirmado» tras timeout, error de red o 5xx, el resultado es ambiguo: el aviso podría haberse creado. Consulta list_my_avisos y, solo si no aparece, crea una nueva previsualización y pide confirmación otra vez. Un 4xx sí descarta la creación.

Skill reutilizable

El artefacto de instrucciones, independiente de cualquier plataforma o harness, está en skill/SKILL.md. Su instalación es manual: colócalo en el directorio de skills que admita tu cliente. Mantén el proceso MCP en un entorno con acceso a las rutas locales que le proporciones; este proyecto no modifica configuraciones externas.

🌐 Soporte Multi-Ayuntamiento

Aunque está preconfigurado por defecto para Chiclana de la Frontera (ID 268), el servidor está pensado para los municipios que usan GECOR (Torremolinos, Vélez-Málaga, Viladecans, etc.).

Para listar todos los municipios disponibles:

node dist/cli.js ayuntamientos

Para usar otro municipio por defecto, define la variable de entorno:

export GECOR_AYTO_ID=143 # Ejemplo: Torremolinos

💻 CLI de Apoyo

Se incluye una utilidad de línea de comandos para realizar pruebas directas:

node dist/cli.js ayuntamientos [filtro]    # Buscar municipios GECOR
node dist/cli.js whoami                   # Ver estado de configuración
node dist/cli.js categories [filtro]      # Ver categorías y tipologías
node dist/cli.js photo <foto.jpg>         # Inspeccionar metadatos GPS EXIF (misma restricción de directorios)
node dist/cli.js calles [filtro]          # Consultar callejero oficial

🏗️ Construcción y Desarrollo

npm install
npm run build
npm run typecheck
npm test

📄 Licencia

MIT. Consulta LICENSE.

Inspirado en madrid-avisos-mcp.