Metadata-Version: 2.4
Name: neuroloom-mcp
Version: 0.1.0
Summary: MCP server that gives AI coding agents persistent memory via the Neuroloom API
Project-URL: Homepage, https://neuroloom.dev
Project-URL: Documentation, https://neuroloom.dev/docs
Project-URL: Source, https://github.com/endless-galaxy-studios/neuroloom
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.12
Requires-Dist: cachetools>=5.5.0
Requires-Dist: httpx>=0.28.0
Requires-Dist: mcp>=1.5.0
Requires-Dist: pydantic-settings>=2.7.0
Requires-Dist: uvicorn[standard]>=0.34.0
Provides-Extra: codegraph
Requires-Dist: neuroloom-codeweaver>=0.1.0; extra == 'codegraph'
Provides-Extra: dev
Requires-Dist: mypy>=1.14.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.25.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.9.0; extra == 'dev'
Requires-Dist: types-cachetools>=5.5.0; extra == 'dev'
Description-Content-Type: text/markdown

# neuroloom-mcp

MCP server that gives AI coding agents persistent memory via the Neuroloom knowledge graph API.

## Install via pip

> Requires Python 3.12+

```sh
pip install neuroloom-mcp
neuroloom-mcp install-plugin
```

Then restart Claude Code. The plugin and MCP server are configured together.
Set your API key with `/plugins configure neuroloom` in Claude Code.

To upgrade:

```sh
pip install --upgrade neuroloom-mcp
neuroloom-mcp install-plugin --force
```

---

## Hosted (Cloud) Connection

The Neuroloom MCP server is available as a hosted service — no local installation required.

**Public endpoint:** `https://mcp.neuroloom.dev/mcp`

### Prerequisites

You need a Neuroloom API key. Create one at [app.neuroloom.dev/settings/api-keys](https://app.neuroloom.dev/settings/api-keys).

### Claude Code

Create `.mcp.json` in your project root (the directory where you run Claude Code):

```json
{
  "mcpServers": {
    "neuroloom": {
      "type": "http",
      "url": "https://mcp.neuroloom.dev/mcp",
      "headers": {
        "Authorization": "Bearer nl_your_api_key_here"
      }
    }
  }
}
```

### Other MCP Clients

Any MCP client that supports HTTP (streamable HTTP) transport can connect using the `url` transport type and the `Authorization` header shown above.

> **Claude Desktop:** Claude Desktop currently supports only the stdio transport. To use Neuroloom with Claude Desktop, follow the local stdio setup instructions below.

### Verifying Your Connection

Check MCP server connectivity (unauthenticated):

```bash
curl https://mcp.neuroloom.dev/health
```

Expected response: `{"status": "ok", "version": "0.1.0"}` with HTTP 200.

Validate your API key against the Neuroloom API directly:

```bash
curl -H "Authorization: Token nl_your_api_key_here" https://api.neuroloom.dev/api/v1/workspaces/
```

HTTP 200 confirms the key is valid.

> **Note:** MCP clients send `Authorization: Bearer <key>`; the Neuroloom API uses `Authorization: Token <key>`. The MCP server translates between the two schemes automatically.

### Troubleshooting

| Error | Cause | Fix |
|-------|-------|-----|
| `401 authentication_failed` | API key is invalid or revoked | Create a new key at [app.neuroloom.dev/settings/api-keys](https://app.neuroloom.dev/settings/api-keys) |
| `503 upstream_unavailable` | Neuroloom API is temporarily down | Retry after a moment |
| Connection refused | MCP client doesn't support `url` (streamable HTTP) transport | Check client docs; Claude Desktop only supports stdio |
| Connection timeout | Server unreachable or slow to respond | Check `https://mcp.neuroloom.dev/health` for availability |
| MCP client says it needs to complete an OAuth flow | Client is connecting to an older server version without the OAuth compatibility layer | Upgrade to the latest server version and retry |

## OAuth Compatibility Layer

The server implements `GET /.well-known/oauth-protected-resource` as specified by [RFC 9728](https://www.rfc-editor.org/rfc/rfc9728). Some MCP clients (including newer versions of Claude Code) probe this endpoint before connecting to determine whether they need to start an OAuth authorization flow.

The handler returns an empty `authorization_servers` array, which signals to the client that no OAuth flow is needed — authentication is handled via the `Authorization: Bearer <key>` header that operators and developers already configure.

The implementation lives in `neuroloom_mcp/server.py` (`oauth_protected_resource_handler`). The route is registered without authentication middleware so the discovery probe is always reachable, even before a valid API key is presented.

## Local Development (stdio)

For local use or Claude Desktop, install and run the MCP server as a stdio process.

Requires [uv](https://docs.astral.sh/uv/) (Python package manager).

```bash
cd mcp && uv sync
```

### Required environment variables

| Variable | Description |
|----------|-------------|
| `MEMORIES_API_TOKEN` | API key generated from the Neuroloom dashboard |
| `MEMORIES_WORKSPACE_ID` | Workspace ID found under Settings > Workspaces |
| `MEMORIES_API_URL` | Neuroloom API URL (default: `https://api.neuroloom.dev`) |

```env
# MEMORIES_API_URL=https://api.neuroloom.dev  (default, override for local dev)
MEMORIES_API_TOKEN=your_api_key_here
MEMORIES_WORKSPACE_ID=your_workspace_id_here
```

### Claude Code (stdio)

Add to your project's `.mcp.json`:

```json
{
  "mcpServers": {
    "neuroloom": {
      "type": "stdio",
      "command": "uv",
      "args": ["--directory", "/path/to/neuroloom/mcp", "run", "neuroloom-mcp"],
      "env": {
        "MEMORIES_API_TOKEN": "your_api_key_here",
        "MEMORIES_WORKSPACE_ID": "your_workspace_id_here"
      }
    }
  }
}
```

Replace `/path/to/neuroloom/mcp` with the absolute path to the `mcp/` directory in your local clone.

## Documentation

Full setup guide and configuration reference: https://neuroloom.dev/docs
