Metadata-Version: 2.4
Name: cog-mcp-experimental
Version: 0.2.8
Summary: Unofficial MCP server for Cognite Data Fusion data modeling
Requires-Python: >=3.10
Requires-Dist: cognite-sdk>=7.0.0
Requires-Dist: mcp[cli]>=1.2.0
Requires-Dist: python-dotenv>=1.0.0
Description-Content-Type: text/markdown

# cog-mcp-experimental

MCP server for Cognite Data Fusion data modeling. Exposes data model schemas as resources, instance operations (list, search, query, aggregate, retrieve), and AI document tools (question answering and summarization).

## Quick start

```bash
uvx cog-mcp-experimental
```

## Configuration

Configuration is via environment variables — either passed through your MCP client's config, or loaded from a `.env` file in the working directory.

### Using a `.env` file

Create a `.env` file (and add it to `.gitignore`):

```bash
CDF_CLIENT_ID=your-client-id
CDF_TENANT_ID=your-tenant-id
CDF_CLUSTER=westeurope-1
CDF_PROJECT=your-project
CDF_CLIENT_SECRET=your-secret
CDF_DATA_MODELS=[{"space": "mySpace", "externalId": "MyModel", "version": "1"}]
CDF_INSTANCE_SPACES=["instanceSpace1"]
```

The `.env` file does **not** override existing environment variables — explicit env vars from your MCP client config or shell always take precedence.

### Required environment variables

| Variable | Description |
|---|---|
| `CDF_CLIENT_ID` | OAuth client ID |
| `CDF_TENANT_ID` | Azure AD tenant ID |
| `CDF_CLUSTER` | CDF cluster (e.g. `westeurope-1`) |
| `CDF_PROJECT` | CDF project name |
| `CDF_CLIENT_SECRET` | OAuth client secret |
| `CDF_DATA_MODELS` | JSON array of data models: `[{"space": "s", "externalId": "m", "version": "1"}]` |
| `CDF_INSTANCE_SPACES` | JSON array of space IDs for automatic instance filtering: `["space1"]` |

### Optional

| Variable | Description |
|---|---|
| `CDF_TOKEN_URL` | Override OAuth token URL (defaults to Azure AD) |

## Client setup

### Claude Desktop

`~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "cog-mcp-experimental": {
      "command": "uvx",
      "args": ["cog-mcp-experimental"],
      "env": {
        "CDF_CLIENT_ID": "your-client-id",
        "CDF_TENANT_ID": "your-tenant-id",
        "CDF_CLUSTER": "westeurope-1",
        "CDF_PROJECT": "your-project",
        "CDF_CLIENT_SECRET": "your-secret",
        "CDF_DATA_MODELS": "[{\"space\": \"mySpace\", \"externalId\": \"MyModel\", \"version\": \"1\"}]",
        "CDF_INSTANCE_SPACES": "[\"instanceSpace1\"]"
      }
    }
  }
}
```

### Cursor

`.cursor/mcp.json` or `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "cog-mcp-experimental": {
      "command": "uvx",
      "args": ["cog-mcp-experimental"],
      "env": {
        "CDF_CLIENT_ID": "your-client-id",
        "CDF_TENANT_ID": "your-tenant-id",
        "CDF_CLUSTER": "westeurope-1",
        "CDF_PROJECT": "your-project",
        "CDF_CLIENT_SECRET": "${env:CDF_CLIENT_SECRET}",
        "CDF_DATA_MODELS": "[{\"space\": \"mySpace\", \"externalId\": \"MyModel\", \"version\": \"1\"}]",
        "CDF_INSTANCE_SPACES": "[\"instanceSpace1\"]"
      }
    }
  }
}
```

### Claude Code

```bash
claude mcp add --transport stdio \
  --env CDF_CLIENT_ID=your-client-id \
  --env CDF_TENANT_ID=your-tenant-id \
  --env CDF_CLUSTER=westeurope-1 \
  --env CDF_PROJECT=your-project \
  --env 'CDF_DATA_MODELS=[{"space":"mySpace","externalId":"MyModel","version":"1"}]' \
  --env 'CDF_INSTANCE_SPACES=["instanceSpace1"]' \
  cog-mcp-experimental -- uvx cog-mcp-experimental
```

`CDF_CLIENT_SECRET` is inherited from your shell environment.

## Tools

### Discovery

| Tool | Description |
|---|---|
| `list_views` | List available views with their space, externalId, and version |
| `get_view_schema` | Get full property schema for a view (names, types, relations) |
| `get_filter_docs` | Reference documentation for filter syntax |
| `get_query_docs` | Reference documentation for graph query syntax |

### Instance operations

| Tool | Description |
|---|---|
| `list_instances` | List/filter instances of a view with pagination |
| `search_instances` | Full-text search across instances |
| `aggregate_instances` | Count, sum, avg, min, max, histogram |
| `query_instances` | Graph query across related instances |
| `retrieve_instances` | Get specific instances by ID |

All instance tools automatically apply space filters from `CDF_INSTANCE_SPACES`.

### AI document tools

| Tool | Description |
|---|---|
| `ask_documents_question` | Ask questions about PDF documents using document `instanceId` values |
| `summarize_document` | Summarize a single PDF document using document `instanceId` |

## Resources

The same discovery information is also available as MCP resources for clients that support them:

| URI | Description |
|---|---|
| `cdf://views` | List all available views |
| `cdf://views/{space}/{externalId}/{version}` | View schema with property details |
| `cdf://docs/filters` | Filter syntax reference |
| `cdf://docs/querying` | Query syntax reference |

## Development

```bash
git clone <repo>
cd cog-mcp-experimental
uv sync --dev       # install project + dev dependencies
uv run cog-mcp-experimental  # start the MCP server locally
```

### Common commands

| Command | Description |
|---|---|
| `uv run ruff check src/ tests/ && uv run ruff format --check src/ tests/ && uv run pytest` | Lint + tests (same gate as CI) |
| `uv run pytest` | Run test suite with coverage |
| `uv run ruff check src/ tests/` | Check for lint issues |
| `uv run ruff check --fix src/ tests/ && uv run ruff format src/ tests/` | Auto-fix lint + reformat |
| `uv run pytest -k "<expression>"` | Run a subset of tests |

### Testing with MCP Inspector

```bash
npx @modelcontextprotocol/inspector
```
