valencia-avisos-mcp
Provides geocoding capabilities using ArcGIS to convert street addresses into geographic coordinates, used for locating incidents when creating avisos.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@valencia-avisos-mcp Tengo una foto de un contenedor desbordado en la calle Colón, crea el aviso"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
valencia-avisos-mcp
Servidor MCP (y CLI de apoyo) para el sistema de avisos del Ayuntamiento de
Valencia (AppValencia / viaPublica). Permite a un agente listar categorías,
buscar calles, consultar avisos y crear avisos con inteligencia artificial —
incluso desde una foto. La autenticación (Basic app:app) va integrada: es la
de la propia app, pública en el APK.
La finalidad de este proyecto es hacer más fácil que los ciudadanos puedan reportar problemas al Ayuntamiento de Valencia. Saca una foto de la incidencia (un contenedor desbordado, una farola apagada, una plaga…), pásasela al agente pidiéndole que genere un aviso para que describa el problema, seleccione la categoría, añada la ubicación y lance el aviso al Ayuntamiento.
Inicio rápido
Valencia no usa cuentas: el API acepta la clave fija de la app y cada aviso lleva el teléfono o email del comunicante más un id de dispositivo registrado.
Añade el servidor a tu cliente MCP (ejemplos) o configúralo a mano:
{
"mcpServers": {
"valencia-avisos": {
"command": "npx",
"args": ["-y", "valencia-avisos-mcp"]
}
}
}Verifica:
list_categoriesdebe devolver los 7 grupos (30 códigosTCOM-xxx).Pregunta al humano UNA vez su idioma (
es/va) y su teléfono o email; guárdalos con la toolset_identity. Se reutilizan en todos los avisos.Registra el dispositivo con
register_device(con OK humano: escribe en el Ayuntamiento) y ya puedes crear y consultar.Flujo del agente:
create_aviso_from_photo(foto → categoría → calle → preview) → enseña el preview al humano →confirm: true+human_confirmed: true+preview_tokensolo con su "sí" → comprobación enmy_avisos.
Todo corre en tu máquina; los avisos se crean con la identidad guardada.
Related MCP server: Smart Cities MCP Server
Fotos demasiado grandes para el modelo
Algunos modelos rechazan fotos muy grandes (image decode limit exceeded). El servidor
reduce en TypeScript (sin dependencias) conservando el GPS, así que el modelo nunca
necesita procesar la original:
Remoto (HTTP): sube la foto con curl y usa el
file_id(los bytes no pasan por el modelo). Requiere el secreto del servidor:curl -X PUT --data-binary @foto.jpg \ -H "Authorization: Bearer ***" \ 'http://127.0.0.1:3001/upload?filename=foto.jpg' # → {"file_id":"…","bytes":…}El preview devuelve
preview_image_base64(copia reducida) para visión y el envío usa siempre la original.Local (stdio/CLI): pasa
image_path; el servidor lee y reduce sin que el modelo abra el fichero. O reduce tú connode dist/cli.js prep-photo foto.jpg [foto-ligera.jpg].
¿Eres un agente IA? Lee esto primero
La skill (skill/SKILL.md) no se autoinstala: cópiala al directorio de tu cliente
y abre sesión nueva.
cp -r skill ~/.hermes/skills/valencia-avisos # Hermes
cp -r skill ~/.claude/skills/valencia-avisos # Claude Code
# o descárgala: https://github.com/Naroh091/valencia-avisos-mcp/blob/main/skill/SKILL.mdInstálalo así (requiere Node 18+):
Sin credenciales: este MCP no necesita tokens ni cuentas. Solo idioma + teléfono o email del humano (paso 3 del inicio rápido).
Instalación según tu cliente (comandos exactos): Claude Code (
claude mcp add … -- npx -y valencia-avisos-mcp), Hermes (hermes mcp add … --command npx … --args -y valencia-avisos-mcp) u OpenClaw (openclaw mcp add … --command npx --arg -y --arg valencia-avisos-mcp).Identidad + dispositivo: pregunta idioma y contacto UNA vez (
set_identity, verifica conget_identity) y registra el dispositivo (register_device, con OK humano porque escribe en el servidor).Verifica (
mcp list/test/doctor --probesegún cliente): debes ver 11 tools.Uso: hay skill completa en
skill/SKILL.md. Lo esencial: solo incidencias genuinas;create_aviso_from_photoen fases (categoría → calle → preview → envío solo con "sí" humano +confirm+human_confirmed+preview_token); foto porfile_id; la dirección es texto libre y las coordenadas van como"lat lon".
Añadir el MCP vía npx
Requiere Node 18+.
Claude Code
claude mcp add valencia-avisos -- npx -y valencia-avisos-mcp
claude mcp list # verificarHermes
hermes mcp add valencia-avisos --command npx --args -y valencia-avisos-mcp
hermes mcp test valencia-avisos # verificar (lista las 11 tools)OpenClaw
openclaw mcp add valencia-avisos \
--command npx \
--arg -y \
--arg valencia-avisos-mcp
openclaw mcp doctor valencia-avisos --probe # verificarDesde código
npm install
npm run build
npx -y -p valencia-avisos-mcp valencia-avisos-mcp-http # HTTP en 127.0.0.1:3001/mcpHerramientas MCP
Tool | Qué hace |
| Identidad guardada (contacto, idioma, dispositivo) o null. |
| Guarda idioma + teléfono/email (se pregunta una vez). |
| Registra el cliente en el Ayuntamiento (escribe; solo con OK humano). |
| 7 grupos y 30 códigos |
| Detalle de un código (grupo y nombre). |
| Sugiere códigos por palabras. |
| Calle + número → coordenadas con el callejero municipal. |
| Actuaciones en vía pública (lectura abierta). |
| Avisos del comunicante (por teléfono/email). |
| Crea un aviso. Dry-run por defecto; |
| Aviso desde foto en fases: categoría → calle → preview (GPS EXIF) y envío solo con |
Seguridad de envío
create_aviso es dry-run por defecto: devuelve los campos sin crear nada. Solo con
confirm: true hace el POST real — un aviso real que revisa personal municipal.
Envía únicamente incidencias reales.
create_aviso_from_photo exige confirmación humana en fases:
Categoría (sin
categoria): sugiere y no envía nada.Calle (sin
streetCode): pide calle/portal y no envía nada.Preview (
confirmausente/false): GPS EXIF (olat/lngmanuales), payload +preview_token. No envía nada.Envío: el agente muestra el preview al humano y espera su "sí"; solo entonces repite la llamada con los MISMOS campos +
confirm: true+human_confirmed: true+preview_token. Si cambió cualquier campo, hay que repetir el preview.
Uso como CLI
node dist/cli.js categories
node dist/cli.js category TCOM-270
node dist/cli.js geocode "Calle Colón 1, Valencia"
node dist/cli.js actuaciones
node dist/cli.js identity-set 654321987 nombre@example.com es
node dist/cli.js register-device
node dist/cli.js my-avisos
node dist/cli.js create TCOM-270 39.4674 -0.3746 "CARRER COLÓN 1" -- "Contenedor desbordado" # dry-run
node dist/cli.js create TCOM-270 39.4674 -0.3746 "CARRER COLÓN 1" -- "Contenedor desbordado" --send # ENVÍA de verdad
node dist/cli.js from-photo foto.jpg TCOM-270 "Contenedor desbordado" # preview desde foto
node dist/cli.js prep-photo foto.jpg [foto-ligera.jpg] # reduce para el modelo, conserva EXIF/GPSServidor HTTP (opcional)
Por stdio cada uno corre su copia. La entrada HTTP sirve para exponer el servidor que corre en TU máquina para que un agente en OTRA máquina lo use.
export VALENCIA_AVISOS_MCP_SECRET=<un-secreto-largo> # exige x-mcp-secret o Bearer
export VALENCIA_AVISOS_ALLOWED_HOSTS=tu-host.tu-tailnet.ts.net # anti DNS-rebinding
npm run start:http # 127.0.0.1:3001/mcpVariables: VALENCIA_AVISOS_HTTP_PORT (3001), VALENCIA_AVISOS_HTTP_HOST (127.0.0.1),
VALENCIA_AVISOS_HTTP_PATH (/mcp). Expón solo en red privada (p.ej. tailscale serve,
nunca funnel). Para persistencia, launchd/pm2/tmux o similar.
Arquitectura
src/client.ts— Basic +api=2&lang, POST form/multipart, geocoder ArcGIS.src/identity.ts— contacto/idioma/dispositivo en JSON local (0600), con las regex del formulario de la app.src/avisos.ts— núcleo (categorías, callejero, actuaciones, mis avisos, registro, creación condescripcion/telefono/direccion/localizacion "lat lon"/ correoElectronico/idDispositivo/categoria/imagen1..N).src/photo.ts— foto: EXIF/GPS, subida a tmp, token de preview.src/types.ts— esquemas zod de entrada + payload de creación.src/mcp.ts—buildServer(): registra las 11 tools (compartido por stdio y HTTP).src/server.ts— entrada stdio ·src/http.ts— entrada HTTP (/mcp+PUT /upload) ·src/cli.ts— CLI.
Notas
Ingeniería inversa del APK
es.valencia.lanzaderav2.0.80 + verificación en vivo de lecturas y dry-runs (sin crear avisos reales).
Licencia
AGPLv3. Ver LICENSE.
Available Tools
11 toolsactuacionesC
Actuaciones en vía pública (obras, podas…; lectura abierta, sin registro).
Inputs: lang.
create_avisoA
Crea un aviso. IMPORTANTE: por defecto es DRY-RUN (confirm=false) y solo devuelve los campos que se enviarían, SIN crear nada. Para crear de verdad hay que pasar confirm=true (requiere deviceId registrado). Usa la identidad guardada salvo 'identity'.
Inputs: lat (required), lon (required), address (required), categoria (required), +5 more.
create_aviso_from_photoA
Aviso desde una FOTO en fases. VÍA PREFERIDA: sube la foto con PUT /upload (curl) y pasa file_id; por stdio usa image_path local. Sin categoria → sugiere (need_category). Con categoria pero sin address/coords → error con ayuda (usa geocode). Con todo → preview + preview_token SIN enviar. Envío: MISMOS campos + confirm:true + human_confirmed:true + preview_token (tras 'sí' humano). Sin las tres NO se envía.
Inputs: lat, lon, fuente, address, +10 more.
geocodeA
Calle + número → coordenadas WGS84 con el callejero municipal (p.ej. 'Calle Colón 1, Valencia').
Inputs: query (required).
get_categoryC
Detalle de un código TCOM-xxx: grupo, código y nombre.
Inputs: code (required), lang.
get_identityA
Devuelve la identidad del comunicante guardada (contacto, idioma, dispositivo) o null si aún no se preguntó.
Inputs: no named parameters.
list_categoriesB
Categorías y subcategorías de avisos (cada una trae su código TCOM-xxx para crear).
Inputs: lang.
my_avisosB
Avisos del dispositivo registrado (requiere register_device previo).
Inputs: no named parameters.
register_deviceA
Registra este cliente como dispositivo en el Ayuntamiento (POST /dispositivos) y guarda el idDispositivo. ESCRIBE en el servidor: usar solo con OK humano explícito. Necesario antes de crear o consultar avisos.
Inputs: no named parameters.
set_identityA
Guarda la identidad del comunicante (se pregunta UNA vez tras la instalación y se reutiliza). Valida: teléfono español o email obligatorios (al menos uno).
Inputs: lang (required), userEmail, userPhone.
suggest_categoriesB
Sugiere códigos TCOM-xxx por palabras (p.ej. 'contenedor desbordado').
Inputs: hint.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Cada herramienta tiene un propósito distinto: identidad, registro, categorías, geocodificación, consulta y creación. La única superposición es create_aviso vs create_aviso_from_photo, pero las descripciones aclaran que la segunda es para fotos y con fases; list/get/suggest de categorías se distinguen bien.
Mayoría sigue verbo_sustantivo (get_identity, set_identity, register_device, list_categories, create_aviso) pero hay excepciones en español sin verbo (actuaciones, my_avisos) y geocode es solo verbo. Mezcla de idiomas y convenciones, aunque legible.
11 herramientas es un número adecuado para cubrir identidad, dispositivo, categorías, geocodificación, consulta y creación de avisos. Cada una aporta una operación necesaria, sin redundancia excesiva.
Cubre el ciclo de creación y consulta (listar avisos propios, crear desde texto o foto) pero faltan operaciones de actualización/edición, cancelación/borrado y obtención de un aviso concreto. Es una brecha notable para la gestión completa de avisos.
Maintenance
Related MCP Connectors
Mobility, geocoding and nearby urban services for AI agents.
Connect AI agents to discover services and coordinate real-world tasks.
Human-input bridge for AI agents with voice-first answer links, MCP tools, and HTTP APIs.
214 tools for AI agents over one MCP endpoint: image, video, audio, 3D, data, storage, mail, GPUs.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceProvides integrated access to location-based weather, reporting history, and infrastructure status data for safety reporting systems. It supports both SSE and stdio protocols for flexible integration with various AI agents and clients.-
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to interact with IoT device data from a smart city, including public lighting, water, and gas meters. Supports querying and management via the Model Context Protocol.1MIT
- AlicenseBqualityCmaintenanceEnables an AI agent to list municipal services and categories, query existing reports, and create new reports to the Las Palmas de Gran Canaria city council—including from a photo—with human confirmation before submission.816 npm3AGPL 3.0
- AlicenseBqualityCmaintenanceEnables AI agents to report incidents to the Bilbao City Council (MeJora Bilbao / Bilbo Hobetuz) by listing categories, looking up streets, reviewing existing reports, and creating new ones — including generating a report directly from a geolocated photo. Drafts are dry-run by default and real submissions require explicit human confirmation.1216 npm1AGPL 3.0