Serveur MCP Sofia Data
Commit 10 nov. 2026Permet aux clients IA d'accéder aux jeux de données urbains du portail de la municipalité de Sofia via une intégration CKAN.
Aussi connu sous manevpe/sofia-data-mcp
- Étoiles
- 0
- Outils
- 11
- Téléchargements, 30 jours
- —
- Dernière version
- —
- Dernier commit
- 10 nov. 2026
- Licence
- MIT
Qu'est-ce que Sofia Data MCP ?
Permet aux clients IA d'accéder aux jeux de données urbains du portail de la municipalité de Sofia via une intégration CKAN. Il expose 11 outils, comme search_datasets, get_dataset, list_groups.
Résumé généré à partir du README du projet
À propos du MCP server Sofia Data
Ce serveur permet aux développeurs et aux analystes de données d'interroger les jeux de données urbains du portail de la municipalité de Sofia. En s'intégrant directement à l'API CKAN Action, il fournit une interface permettant aux clients IA d'explorer les informations municipales via des outils tels que search_datasets, list_groups et get_dataset. Le système est conçu pour gérer des métadonnées complexes, incluant la réparation automatique des noms de groupes en cyrillique corrompus et le profilage sémantique basé sur les tags et les formats.
Les utilisateurs peuvent se connecter via un endpoint HTTP public pour un support natif dans Cursor ou VS Code Copilot Chat. Pour les clients limités aux processus locaux comme Claude Desktop, le serveur propose un pont stdio qui redirige les requêtes vers l'URL distante. Il nécessite Node.js 24+ et peut être exécuté localement via pnpm ou déployé sur Google Cloud Run. Le serveur inclut un cache en mémoire pour les lectures CKAN afin d'améliorer les performances et gère les données via des outils spécifiques comme facet_datasets et preview_resource pour inspecter le contenu JSON ou GeoJSON.
Ce que vous pouvez faire avec
- 1Rechercher des jeux de données municipauxUn agent IA peut trouver des fichiers de données urbaines spécifiques en interrogeant le catalogue de la municipalité.
- 2Analyser la distribution des donnéesLes utilisateurs peuvent demander le décompte des jeux de données classés par licence, format ou organisation.
Extrait du README du projet. Chaque cas d'utilisation est vérifié par rapport à une citation du document.
Outils MCP Sofia Data 11
Détectés depuis le READMEsearch_datasetsget_datasetlist_groupsget_grouplist_organizationsget_organizationlist_dataset_resourcespreview_resourcesummarize_datasetfind_related_datasetsfacet_datasets
| search_datasets | — | |
| get_dataset | — | |
| list_groups | — | |
| get_group | — | |
| list_organizations | — | |
| get_organization | — | |
| list_dataset_resources | — | |
| preview_resource | — | |
| summarize_dataset | — | |
| find_related_datasets | — | |
| facet_datasets | — |
Configuration
E2E_BASE_URL
| Nom | Description | Type |
|---|---|---|
| E2E_BASE_URL | — |
Vérifications automatisées
Exécuté le 14 nov. 2026Rapport complet →Pas encore vérifié. Un serveur nécessite un score de 80, aucune faille sérieuse et suffisamment de données pour que nous puissions effectuer les vérifications. Fonctionnement des vérifications · Ce qu'il faut corriger pour gagner des points
- Dépôt source lié et accessiblemanevpe/sofia-data-mcp is public and reachablegithub.com/manevpe/sofia-data-mcp ↗Réussi
- Le nom du package correspond au dépôt sourceNon vérifié
- Provenance du build (attestation Sigstore)Non vérifié
- Licence open source (OSI)MITspdx.org/licenses/MIT.html ↗Réussi
- Commit ou version publiée au cours de l'année écouléeLast commit or release 2026-11-10github.com/manevpe/sofia-data-mcp ↗Réussi
- OpenSSF ScorecardNon vérifié
- Nom du package non proche d'un package populaireNon vérifié
- Aucun avis critique dans le package ou ses dépendancesNon vérifié
- Aucune instruction cachée destinée au modèle11 tool descriptions and the README read; no override phrases, credential paths or hidden charactersRéussi
- Les outils destructifs sont étiquetésNo tool named like delete, drop or execRéussi
- Le point de terminaison distant répond à la poignée de main MCPNon vérifié
README
Voir sur GitHubSofia Data MCP
TypeScript MCP server, stdio bridge, and CLI client for the Sofia municipality urban data portal at https://urbandata.sofia.bg.
Architecture
- Canonical server transport: Streamable HTTP
- Desktop compatibility transport: local
stdiobridge that forwards to HTTP - Local default endpoint:
http://127.0.0.1:3000/mcp - Source portal integration: CKAN Action API
Connect an MCP Client
The deployed server is public, requires no auth, and speaks Streamable HTTP at:
https://sofia-data-mcp-oparjiwnqa-ew.a.run.app/mcp
Clients with native remote/HTTP MCP support (recommended)
VS Code (Copilot Chat) — add to .vscode/mcp.json in your project (or
your user mcp.json via the MCP: Open User Configuration command):
{
"servers": {
"sofia-data": {
"type": "http",
"url": "https://sofia-data-mcp-oparjiwnqa-ew.a.run.app/mcp"
}
}
}
Cursor — add to .cursor/mcp.json:
{
"mcpServers": {
"sofia-data": {
"url": "https://sofia-data-mcp-oparjiwnqa-ew.a.run.app/mcp"
}
}
}
Clients that only support local stdio servers (e.g. Claude Desktop)
Claude Desktop's claude_desktop_config.json only launches local processes,
so bridge to the remote HTTP endpoint with the widely-used mcp-remote
adapter (no install/build required, runs via npx):
{
"mcpServers": {
"sofia-data": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://sofia-data-mcp-oparjiwnqa-ew.a.run.app/mcp"
]
}
}
}
Alternatively, this repo's own @sofia-data/stdio-bridge package works the
same way — point it at the deployed URL instead of running the server
locally:
pnpm --filter @sofia-data/stdio-bridge dev -- \
--upstream-url https://sofia-data-mcp-oparjiwnqa-ew.a.run.app/mcp
Quick smoke test (no client needed)
curl -s https://sofia-data-mcp-oparjiwnqa-ew.a.run.app/health
Packages
@sofia-data/core: shared CKAN client, normalization, analytics, and MCP tool definitions@sofia-data/http-server: HTTP MCP server@sofia-data/stdio-bridge:stdiobridge to an HTTP MCP server@sofia-data/cli: bilingual CLI client
Requirements
- Node.js 24+
- Corepack available
Install
corepack enable
corepack prepare pnpm@10.8.1 --activate
pnpm install
Build
pnpm build
Run Locally
Start the HTTP server:
pnpm dev:server
Default endpoint:
http://127.0.0.1:3000/mcp
Run the CLI:
pnpm dev:cli
Run the stdio bridge:
pnpm dev:bridge
Override the bridge upstream URL:
pnpm --filter @sofia-data/stdio-bridge dev -- --upstream-url http://127.0.0.1:3000/mcp
Docker
Build and run with Docker Compose:
docker compose up --build
End-to-End Tests
packages/e2e runs a full black-box smoke test against a deployed
instance (health check, MCP initialize handshake, listTools, and a real
search_datasets call) — distinct from packages/http-server's unit tests,
which spin up a local in-process server. It's skipped automatically (not
failed) when no target is given, so it never affects normal pnpm test/CI:
E2E_BASE_URL=https://sofia-data-mcp-oparjiwnqa-ew.a.run.app pnpm test:e2e
This also runs automatically as a post-deploy gate in
.github/workflows/deploy.yml, against the URL of the revision that was
just deployed.
Deploying to Google Cloud Run
See deploy/gcp/README.md for scripts that deploy
http-server to Cloud Run (capped at 1 instance) with an automated budget
kill-switch that scales the service to zero if spend reaches a configured
threshold (default $2).
Environment Variables
Copy .env.example and adjust as needed.
Key values:
SOFIA_CKAN_BASE_URLHOSTPORTMCP_HTTP_PATHREQUEST_TIMEOUT_MS=30000PREVIEW_MAX_BYTES=262144MAX_SEARCH_RESULTS=50CACHE_TTL_MS=300000— in-memory TTL cache for CKAN reads (groups, organizations, search results, dataset lookups). Set to0to disable caching.ALLOWED_HOSTS/ALLOWED_ORIGINS— comma-separated extra hostnames/origins (beyond127.0.0.1/localhost) allowed to reach the MCP endpoint. Required when deploying publicly (e.g. Cloud Run) so the server's own DNS-rebinding/CORS protection doesn't reject requests to its own public hostname. Left unset, the server only accepts local traffic.MCP_UPSTREAM_URLMCP_SERVER_URL
Tools
search_datasetsget_datasetlist_groupsget_grouplist_organizationsget_organizationlist_dataset_resourcespreview_resourcesummarize_datasetfind_related_datasetsfacet_datasets— returns catalog-wide counts (group/organization/format/license) computed by CKAN's native faceting, not a client-side count over a capped page of results
Dataset Metadata Enrichment
Dataset summaries include a semanticProfile field generated generically from CKAN
metadata alone (groups, tags, resource formats) — there is no per-dataset hardcoded
knowledge to maintain, so it scales automatically as datasets are added or renamed on the
portal. For exact field-level structure, use summarize_dataset or preview_resource,
which parse an actual sampled resource (JSON/GeoJSON) to report real geometry types and
property/field names.
Group names that were corrupted by a source-side Cyrillic transliteration/encoding bug
(e.g. bnopa3hoo6pa3ne) are automatically repaired using a generic transliteration of the
group's title, rather than a hardcoded name-to-name mapping.
Testing
Each package has a unit test suite using Node's built-in test runner:
pnpm test
CI runs pnpm build, pnpm check (typecheck), and pnpm test on every push/PR to main
(see .github/workflows/ci.yml).
Automated dependency updates
Dependabot (.github/dependabot.yml) checks weekly for updates to npm/pnpm packages,
GitHub Actions, and the Docker base image, grouping patch/minor updates into a single PR
per ecosystem. .github/workflows/dependabot-auto-merge.yml automatically approves and
enables auto-merge for patch/minor version PRs; the merge only completes once the
required build-and-test CI check passes on that PR (enforced by branch protection on
main). Major version bumps are left for manual review.
Notes
- Technical naming is English-only.
- CLI display text is bilingual and rendered as two lines with English first.
- Source metadata from the portal is preserved as published.
Questions sur Sofia Data MCP
Quels outils Sofia Data MCP fournit-il ?
Il expose 11 outils, dont search_datasets, get_dataset, list_groups, get_group, list_organizations.
Le serveur nécessite-t-il une authentification ?
Non, le serveur déployé est public et ne nécessite aucune authentification.