Metadata-Version: 2.4
Name: cortex-research-mcp
Version: 0.1.0
Summary: MCP connector for the Cortex Research gateway (TimescaleDB, Motherduck, Neo4j, Qdrant)
License: Proprietary
Requires-Python: >=3.10
Requires-Dist: mcp>=1.23.0
Requires-Dist: requests>=2.32.0
Description-Content-Type: text/markdown

# Cortex Research MCP Connector

A one-command connector that gives your AI IDE (Claude Code, Cursor, Codex)
direct, no-repo-clone access to the Cortex research data sources —
TimescaleDB, Motherduck, Neo4j, and Qdrant — via the production gateway at
`https://wasif-cortex.fly.dev`. No manual Python environment, no cloning this
repo. Just two steps.

## What you need

- A Cortex collaborator API key (`cortex_...`). Ask Wasif to add your email
  to the collaborator key list if you don't have one yet.
- macOS/Linux/Windows with a terminal.

## Step 1 — install `uv` (one-time, ~10 seconds)

`uv` is a fast Python package/tool runner. If you don't already have it:

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

(Windows: see https://docs.astral.sh/uv/getting-started/installation/)

That's it — you do NOT need to separately install Python, create a virtual
environment, or clone this repository.

## Step 2 — add the connector to Claude Code

```bash
claude mcp add cortex-research --env CORTEX_API_KEY=cortex_xxxxxxxx -- \
  uvx --from cortex-research-mcp cortex-research-mcp
```

Replace `cortex_xxxxxxxx` with your actual key. That's the entire setup.
`uvx` downloads and runs the connector in an isolated, cached environment —
nothing to maintain, nothing to update manually.

> **Interim note (pre-PyPI-publish):** until this package is published to
> PyPI (see "Publishing to PyPI" below), Wasif will hand you a built wheel
> file (`cortex_research_mcp-0.1.0-py3-none-any.whl`) instead. Use:
> ```bash
> claude mcp add cortex-research --env CORTEX_API_KEY=cortex_xxxxxxxx -- \
>   uvx --from /absolute/path/to/cortex_research_mcp-0.1.0-py3-none-any.whl cortex-research-mcp
> ```
> Once published, drop the `/absolute/path/to/...whl` and use the plain
> package name shown in Step 2 — same command shape either way.

## Alternative: `.mcp.json` snippet

Drop this into your project's `.mcp.json` (or global MCP config):

```json
{
  "mcpServers": {
    "cortex-research": {
      "command": "uvx",
      "args": ["--from", "cortex-research-mcp", "cortex-research-mcp"],
      "env": {
        "CORTEX_API_KEY": "cortex_xxxxxxxx"
      }
    }
  }
}
```

## Environment variables

| Variable | Required | Default | Purpose |
|---|---|---|---|
| `CORTEX_API_KEY` | Yes | none | Your collaborator API key, sent as `X-API-Key` |
| `CORTEX_API_URL` | No | `https://wasif-cortex.fly.dev` | Gateway base URL override |

Never commit your `CORTEX_API_KEY` to git or paste it into shared files.

## Tools exposed

| Tool | Purpose |
|---|---|
| `query_timescale(sql_query, limit=200)` | Read-only SELECT against TimescaleDB |
| `query_motherduck(sql_query, limit=200)` | Read-only SQL against the Motherduck panel |
| `query_neo4j(cypher_query, limit=100)` | Read-only Cypher against the Neo4j knowledge graph |
| `query_qdrant(query_text, limit=10)` | Semantic search against Qdrant vector memory |
| `write_timescale(sql_query)` | Write/insert into sandbox `research_*` tables (server-enforced allowlist) |
| `publish_finding(name, cagr, max_dd, sharpe, logic_desc, parameters=None)` | Publish a finding to the team promotion queue |
| `get_northstar()` | Fetch the current research NORTHSTAR.md |
| `whoami()` | Confirm your API key works and see your collaborator identity |

## Troubleshooting

- **401 Unauthorized**: your `CORTEX_API_KEY` is missing, invalid, or expired.
  Double-check the env var is set in your MCP server config, or ask Wasif to
  verify/add your key.
- **403 Forbidden**: your key is valid but not authorized for that specific
  action (e.g., a write outside the sandbox allowlist). Ask Wasif to check
  your collaborator role.
- **Server won't start**: confirm `uv`/`uvx` is on your `PATH` (`uvx --version`).

## For maintainers: building and testing locally

This directory is a standard installable Python package (`cortex-research-mcp`,
console entry point `cortex-research-mcp`, import package `mcp_cortex`).

```bash
cd research/sdk/mcp_cortex
uv build                     # produces dist/*.whl
uvx --from dist/cortex_research_mcp-0.1.0-py3-none-any.whl cortex-research-mcp
```

Local tool-listing smoke test (no network, no API key needed):

```bash
uv run --with dist/cortex_research_mcp-0.1.0-py3-none-any.whl python3 -c "
import asyncio
from mcp_cortex.server import mcp
async def main():
    tools = await mcp.list_tools()
    print([t.name for t in tools])
asyncio.run(main())
"
```

This should print all 8 tool names.

## Publishing to PyPI (recommended final step — needs Wasif's PyPI account)

Once published, collaborators can drop the wheel path entirely and use the
plain `uvx --from cortex-research-mcp cortex-research-mcp` command shown in
Step 2. Publishing requires a PyPI account with the `cortex-research-mcp`
name registered (or scoped, e.g. `wasif-cortex-research-mcp`, if the bare
name is taken) — this is Wasif's account/credentials, not something a
collaborator can do themselves.

```bash
cd research/sdk/mcp_cortex
uv build
uv publish   # prompts for a PyPI API token (or set UV_PUBLISH_TOKEN)
```

After publishing, no code change is needed here — `uvx --from
cortex-research-mcp` will resolve from PyPI automatically.
