Metadata-Version: 2.4
Name: agimus-mcp
Version: 0.4.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 (13)

**Discovery:**

| Tool | What it does |
|------|--------------|
| `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.

## Programmatic use

```python
from agimus_mcp import create_server

create_server(api_key="agm_...").run()
```

## Security model

* The server authenticates with your Agimus API key — it can only see what the
  key allows.
* It runs locally as a subprocess of your AI tool. No hosted server, no open
  ports.
* All API calls go to `https://api.agimus.ai` (or your configured base URL)
  over HTTPS.

## Development

This package lives in the Agimus monorepo at `sdk/python-mcp/` alongside the
[`agimus`](../python) Python SDK that it wraps.

```bash
cd sdk/python-mcp
pip install -e ".[dev]"
pytest
```

The package depends on a published `agimus` SDK — for development against an
unreleased SDK, install both in editable mode:

```bash
pip install -e ../python -e ".[dev]"
```

## License

MIT
