Metadata-Version: 2.4
Name: ogm-agent-bridge
Version: 0.1.6
Summary: MCP bridge for OpenGraphMemory
Project-URL: Homepage, https://github.com/ardiannurcahya/ogm-agent-bridge
Project-URL: Repository, https://github.com/ardiannurcahya/ogm-agent-bridge
Project-URL: Issues, https://github.com/ardiannurcahya/ogm-agent-bridge/issues
Author: Ardian Nurcahya
License: MIT License
        
        Copyright (c) 2026 Ardian Nurcahya
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: httpx<1,>=0.27
Requires-Dist: mcp<2,>=1.0
Requires-Dist: python-dotenv<2,>=1
Description-Content-Type: text/markdown

# ogm-agent-bridge

MCP stdio bridge from Claude Code, OpenCode, and Hermes to one OpenGraphMemory project.

Bridge uses authenticated OpenGraphMemory REST APIs only. It is stateless: no local database, session mapping, direct PostgreSQL, Neo4j, or object-store access.

## Status

Alpha. PyPI releases are published from GitHub Actions on `v*` tags. Source install is also supported for development.

## Tools

- `ogm_health`
- `ogm_list_datasets`
- `ogm_search_entities`
- `ogm_get_entity`
- `ogm_get_neighbors`
- `ogm_find_path`
- `ogm_get_subgraph`
- `ogm_get_graph`
- `ogm_get_evidence`
- `ogm_get_relation_evidence`
- `ogm_upload_document`

Read tools inspect PostgreSQL-authoritative graph data and evidence. `ogm_upload_document` is only write tool. No delete, update, admin, project-create, relation-review, analytics-refresh, memory, or semantic-retrieval tools exist.

## Install

Install from PyPI with `uv`:

```bash
uv tool install ogm-agent-bridge
```

Or run without installing:

```bash
uvx ogm-agent-bridge --version
```

`pipx` also works:

```bash
pipx install ogm-agent-bridge
```

For source development:

```bash
git clone https://github.com/ardiannurcahya/ogm-agent-bridge.git "$HOME/src/ogm-agent-bridge"
cd "$HOME/src/ogm-agent-bridge"
uv sync --locked
```

## Configure

Set these environment variables before starting your MCP client:

```env
OGM_BASE_URL=http://localhost:8000
OGM_API_KEY=<project-api-key>
OGM_PROJECT_ID=<project-uuid>
OGM_PERMISSION_PROFILE=read-only
```

Use `OGM_PERMISSION_PROFILE=read-only` for graph search only. Use `OGM_PERMISSION_PROFILE=personal-safe` only when reviewed document uploads are needed.

Optional upload roots:

```env
OGM_UPLOAD_ROOTS=/absolute/path/to/allowed/docs
```

More options: [Configuration](docs/configuration.md).

## MCP Client Setup

### Claude Code

Add MCP server config to project `.mcp.json`:

```json
{
  "mcpServers": {
    "ogm": {
      "command": "uvx",
      "args": ["ogm-agent-bridge"],
      "env": {
        "OGM_BASE_URL": "${OGM_BASE_URL}",
        "OGM_API_KEY": "${OGM_API_KEY}",
        "OGM_PROJECT_ID": "${OGM_PROJECT_ID}",
        "OGM_PERMISSION_PROFILE": "${OGM_PERMISSION_PROFILE}"
      }
    }
  }
}
```

Verify:

```bash
claude mcp list
```

### OpenCode

Add MCP server config to `opencode.json` or `opencode.jsonc`:

```json
{
  "mcp": {
    "ogm": {
      "type": "local",
      "command": ["uvx", "ogm-agent-bridge"],
      "environment": {
        "OGM_BASE_URL": "{env:OGM_BASE_URL}",
        "OGM_API_KEY": "{env:OGM_API_KEY}",
        "OGM_PROJECT_ID": "{env:OGM_PROJECT_ID}",
        "OGM_PERMISSION_PROFILE": "{env:OGM_PERMISSION_PROFILE}"
      },
      "enabled": true
    }
  }
}
```

Restart OpenCode after editing config.

### Hermes

Add server under `mcp_servers`:

```yaml
mcp_servers:
  ogm:
    command: "uvx"
    args:
      - "ogm-agent-bridge"
    env:
      OGM_BASE_URL: "${OGM_BASE_URL}"
      OGM_API_KEY: "${OGM_API_KEY}"
      OGM_PROJECT_ID: "${OGM_PROJECT_ID}"
      OGM_PERMISSION_PROFILE: "${OGM_PERMISSION_PROFILE}"
    enabled: true
```

Verify:

```bash
hermes mcp test ogm
```

For source development, replace `uvx ogm-agent-bridge` with:

```bash
uv run --project /absolute/path/ogm-agent-bridge ogm-agent-bridge
```

MCP uses stdio. Diagnostics go to stderr.

## Use

After MCP server is connected, ask your agent to use OGM tools. Start with health and dataset discovery:

```text
Call ogm_health, then ogm_list_datasets.
```

Search entities in one dataset:

```json
{"dataset_id":"dataset-id","q":"OpenGraphMemory","limit":10}
```

Inspect graph context with `ogm_get_entity`, `ogm_get_neighbors`, `ogm_get_subgraph`, `ogm_get_graph`, or `ogm_find_path`. Use `ogm_get_relation_evidence` or `ogm_get_evidence` before making evidence-backed claims.

Upload documents only when profile is `personal-safe` and file path is under `OGM_UPLOAD_ROOTS`:

```text
Call ogm_upload_document with an approved local file path and dataset/project context.
```

## More Docs

- [Claude Code](docs/claude-code.md)
- [OpenCode](docs/opencode.md)
- [Hermes](docs/hermes.md)
- [Configuration](docs/configuration.md)
- [Tool schemas](docs/tools.md)

## Validation

```bash
uv sync --dev --locked
uv run ruff format --check .
uv run ruff check .
uv run mypy src
uv run pytest -q
uv build
```

## Security

Use project-scoped keys. Keep `.env` and keys outside upload roots. Start `read-only`; use `personal-safe` only for reviewed document uploads. See [security](docs/security.md).

## License

MIT. See [LICENSE](LICENSE).
