atlas2-mcp/README.md

atlas2-mcp

Python FastMCP server for the atlas2 resolution flow.

Current status

• Exposes one tool: resolve()
• resolve() now performs the working path:
  • store lookup (label/alias)
  • Wikidata fallback using wikidata.reconci.link quick-resolve (single-candidate)
  • minimal persist to Virtuoso via MCP
  • cache hits return the stored result when confidence is sufficient
• Resolve supports strategy modes:
  • quick
  • ranked
  • interactive
  • hybrid
  • llm_select
• Ranking can use embeddings via Ollama when strategy.use_embeddings=true
• confidence controls cache reuse and re-resolution, not just the resolved/not-found status
• Store lookup was debugged and made robust by splitting label-first then alias.
• Maintenance scaffolding (dry-run CLI) exists to upgrade atlas:needsCuration true entities using:
  • ontology/wikidata_subclassof.ttl
  • Wikidata entity dumps
  • Atlas type bucket inference (Person/Organization/Location/etc.)

Resolver tests

• ./test_resolve.sh runs resolver-focused tests only
• It prints the subjects under test and a per-test timing table

How to run

1) Create config:

cp .env.example .env

2) Install dependencies:

pip install -r requirements.txt

3) Start:

./run.sh

Server runs on port 8550 and mounts the MCP endpoint at /mcp.