Metadata-Version: 2.4
Name: agimus-mcp
Version: 0.5.0
Summary: MCP server for the Agimus data platform — connects AI coding tools to your ontology
Project-URL: Homepage, https://agimus.ai
Project-URL: Repository, https://github.com/agimus-ai/agimus-platform
Project-URL: Issues, https://github.com/agimus-ai/agimus-platform/issues
Author-email: Agimus <support@agimus.ai>
License: MIT
Keywords: agimus,ai,data-platform,llm,mcp,ontology
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: agimus>=0.4.0
Requires-Dist: mcp>=1.2.0
Requires-Dist: pydantic>=2.7
Description-Content-Type: text/markdown

# Agimus MCP Server

Connects AI coding tools — Claude Desktop, Claude Code, Cursor, OpenAI Codex,
and other [Model Context Protocol](https://modelcontextprotocol.io) clients —
to the Agimus data platform. The server gives the AI live awareness of your
ontology (entities, properties, links, types) and bundled reference docs for
the Agimus Python SDK, so it writes correct code instead of guessing field
names.

## What the AI gets

### Tools (14)

**Discovery:**

| Tool | What it does |
|------|--------------|
| `agimus_semantic_schema_search` | Natural-language search over entity/property/link descriptions |
| `agimus_list_entities` | Every entity, with PK, property/link counts |
| `agimus_get_entity_schema` | Full schema for one entity (properties + rich link details) |
| `agimus_list_links` | Every link in the ontology (both directions per link) |
| `agimus_get_link` | Full details for a link by api_name |
| `agimus_list_datasets` | All datasets, optionally filtered by source/name |
| `agimus_get_dataset_schema` | Columns, types, row count + SDK usage snippet |
| `agimus_whoami` | Tenant name, scope, rate limit for the current API key |

**Read (read-only — writes happen via the SDK in user code):**

| Tool | What it does |
|------|--------------|
| `agimus_query_objects` | Filter / sort / project / expand / paginate |
| `agimus_get_object` | Single object by primary key |
| `agimus_get_related_objects` | Traverse a link from one object (cursor-paginated) |
| `agimus_count_objects` | Cheap COUNT(*) with optional filter |
| `agimus_distinct_values` | Distinct values, optionally with frequency counts |
| `agimus_aggregate` | group_by + metrics (count/sum/avg/min/max/...) |

### Resources

* `agimus://schema/entities/{entity}` — live, full schema for one entity
* `agimus://docs/sdk-reference` — the full Agimus Python SDK reference
  (sourced directly from the SDK's README so it never drifts)

## Install & configure

The recommended path is [`uvx`](https://docs.astral.sh/uv/) — it auto-installs
the latest version on first run and keeps it isolated. No prior `pip install`
is required.

### Claude Code

Add to `~/.claude/claude_code_config.json`:

```json
{
  "mcpServers": {
    "agimus": {
      "command": "uvx",
      "args": ["agimus-mcp"],
      "env": { "AGIMUS_API_KEY": "agm_your_api_key_here" }
    }
  }
}
```

### Cursor

Create `.cursor/mcp.json` in your project root:

```json
{
  "mcpServers": {
    "agimus": {
      "command": "uvx",
      "args": ["agimus-mcp"],
      "env": { "AGIMUS_API_KEY": "agm_your_api_key_here" }
    }
  }
}
```

### OpenAI Codex

Add to `~/.codex/config.toml`:

```toml
[mcp_servers.agimus]
command = "uvx"
args = ["agimus-mcp"]
env = { AGIMUS_API_KEY = "agm_your_api_key_here" }
```

### Claude Desktop

Add to `claude_desktop_config.json` (Claude → Settings → Developer → Edit Config):

```json
{
  "mcpServers": {
    "agimus": {
      "command": "uvx",
      "args": ["agimus-mcp"],
      "env": { "AGIMUS_API_KEY": "agm_your_api_key_here" }
    }
  }
}
```

## Alternative install: `pip`

If you prefer a pinned global install:

```bash
pip install agimus-mcp
```

Then replace `"command": "uvx", "args": ["agimus-mcp"]` with
`"command": "agimus-mcp"` in any config above.

## CLI options

```text
agimus-mcp [--api-key agm_xxx] [--base-url URL] [--timeout SECONDS] [--log-level LEVEL]
```

Every flag has an environment-variable equivalent:

| Flag | Env var | Default |
|------|---------|---------|
| `--api-key` | `AGIMUS_API_KEY` | _(required)_ |
| `--base-url` | `AGIMUS_BASE_URL` | `https://api.agimus.ai` |
| `--timeout` | `AGIMUS_TIMEOUT` | `30` |
| `--log-level` | `AGIMUS_LOG_LEVEL` | `WARNING` |

Logs are written to stderr — stdout is reserved for the MCP stdio protocol.

## License

MIT
