# Atlas MCP

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.2 status
Atlas v0.0.2 establishes the new entity-centered canonical model:
- entity core fields are stable (`atlas_id`, `canonical_label`, `entity_type`)
- claims are attached to the entity and carry per-claim provenance/timestamps
- `atlas_id` is now opaque/hash-based (no semantic parsing)
- MID/QID are represented as identifier claims (not encoded in IDs)
- trends/wikidata payload timestamp semantics are harmonized around `retrieved_at`

See `RELEASE_NOTES_v0.0.2.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:

```bash
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.