Metadata-Version: 2.5
Name: agimus-mcp
Version: 1.0.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<2,>=1.0
Requires-Dist: mcp<3,>=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, categories, types), reads of live
data as object sets, and the Agimus Python SDK reference, so it writes
correct code instead of guessing field names. There is no dataset surface:
every read is an entity of the ontology.

## What the AI gets

### Tools (13)

**Discovery:**

| Tool | What it does |
|------|--------------|
| `agimus_semantic_schema_search` | Natural-language search over entity, property and link descriptions; `categories=[...]` scopes by domain |
| `agimus_list_entities` | Every entity, with its primary key, property and link counts, categories and tier; `categories=[...]` filters |
| `agimus_get_entity_schema` | Full schema for one entity: properties with types and declarations, links with cardinality and direction, categories, and the SDK line for bulk |
| `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_categories` | Every category with access-filtered entity counts |
| `agimus_get_category` | One category and its entities |
| `agimus_whoami` | Tenant name, scope and rate limit of the current API key |

**Read (read-only; bulk and writes happen through the SDK in user code):**

Every read is one object set: an entity and ordered steps (`filter`,
`pivot`, `with`, `top`); a filter is a clause, `and`/`or`/`not`, or a link
predicate (`{"link": L, "any": F}`, `{"link": L, "none": F}`). The steps
parameter's description carries the grammar.

| Tool | What it does |
|------|--------------|
| `agimus_query_set` | A page of the objects of a set (sort, fields, expand, cursor; at most 500 per call) |
| `agimus_count_set` | The exact count of a set |
| `agimus_distinct_set` | The distinct values of one field over a set, optionally with counts |
| `agimus_aggregate_set` | Exact metrics over a set, grouped by values, time grains or ranges |
| `agimus_get_object` | One object by primary key |

The related objects of one object are a filter on its key and a pivot. Every
set tool takes an optional `plane` (`operational` or `analytical`) to choose
which plane serves the set; the platform chooses when it is omitted, and a
plane that cannot serve the set is refused at once with the entity named.

### 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.

Requires Python 3.10 or later and the `agimus` SDK 1.x, which it installs.

## License

MIT
