atlas-mcp/README.md

Atlas MVP

Atlas-MCP implements the semantic intelligence tier for the existing MCP stack. It follows the manifest’s mandate: Atlas is the only layer that resolves and enriches entities. For now, Atlas has exactly two public responsibilities: entity resolution and enrichment. The facts-mcp docs reinforce the same design pressure: keep the authoritative truth layer small, canonical, and explicit; Atlas should not blur into that role, but instead cooperate with it through clean graph contracts.

Today’s goals

1. Bootstrap the FastMCP + FastAPI service with the basic /health route and deployment scripts so the runtime mirrors our other MCP servers.
2. Capture the goals for news-mcp integration: entity resolution and enrichment only for now; trend discovery, persistence, and caching remain design concerns but are not first-cut Atlas tools.
3. Document the folder layout, plans, and dependencies so future contributors can extend it safely.

Architecture snapshot

• FastMCP powers the service boundary and service registration.
• FastAPI + Uvicorn provide the HTTP interface (including /health) on port 8550 by default.
• Household scripts (run.sh, killserver.sh, restart.sh) mirror the operational pattern from other MCP projects.
• Ontologies and enrichment: Atlas ingests external definitions, normalizes them into the canonical schema, runs expand(entity, constraints, depth) workflows, and emits resolved/enriched representations. Persistence and caching will come later.
• Type intelligence: resolution now feeds a pipeline of (1) local cache, (2) Virtuoso cache, (3) Google Trends evidence, (4) Wikidata wbsearchentities + Special:EntityData lookups (direct HTTP, with a proper user-agent/contact), (5) optional LLM classification (Groq meta-llama/llama-4-scout-17b-16e-instruct by default, falling back to OpenAI gpt-4o-mini) with optional caller-provided context, then finally the manual curation flag if everything fails.
• News-mcp / Virtuoso-mcp collaboration: news-mcp asks Atlas to resolve text into canonical IDs; Atlas performs enrichment. Trends may assist resolution, but the resolution logic belongs in Atlas, not news-mcp. When Atlas eventually stores or recalls triples it must do so via virtuoso-mcp only; direct connections to the underlying Virtuoso instance are off-limits.

Folder layout sketch

atlas-mcp/
├── README.md
├── PROJECT.md
├── requirements.txt
├── gitignore
├── app/
│   ├── __init__.py
│   └── main.py
├── scripts/
│   ├── run.sh
│   ├── killserver.sh
│   ├── restart.sh
│   └── tests.sh
└── MANIFEST.md ← existing architecture manifesto (reference)

v0.0.1 status

Atlas v0.0.1 is the first stable slice of the entity-resolution pipeline:

• MCP-first resolve_entity / enrich_entity
• automatic persistence hook inside resolution
• active-claims-only normal responses
• debug responses with raw/derived claims and Turtle dump
• claim-level provenance and Wikidata lookup

See RELEASE_NOTES_v0.0.1.md for the full summary.

Next steps

• Keep the /health endpoint as a minimal service check on port 8550.
• Wire in configuration placeholders for news-mcp and virtuoso-mcp credentials so Atlas can resolve entities and enrich them.
• Continue tightening claim lifecycle handling and store/read roundtrips via virtuoso-mcp.

Ontology + graph URIs

• Atlas’ current ontology file lives in ontology/atlas.ttl; load that into Protege to inspect the classes/predicates.
• The ontology uses the atlas: prefix for http://world.eu.org/atlas_ontology#, and stored data should use atlas_data: for http://world.eu.org/atlas_data#.
• Override them via .env (ATLAS_PREFIX_IRI, ATLAS_GRAPH_IRI) if you need a different URI, but keep it consistent across Protege, the ontology file, and the data graph.

Quick mcporter check

After restarting Atlas, you can test the server with your local config file like this:

mcporter --config "$CONFIG" call atlas.resolve_entity subject=Trump context="Short snippet for disambiguation"

If your config uses a different server name, swap atlas for that name. The optional context argument is forwarded to the LLM classifier when needed. The /health route is separate and should be checked with HTTP, not mcporter.