Metadata-Version: 2.4
Name: neo-mcp
Version: 0.4.25
Summary: MCP server for the Neo AI/ML backend — submit tasks, poll status, read output
License: MIT
Project-URL: Homepage, https://heyneo.so
Project-URL: Repository, https://github.com/NeoResearchAI/MCPServer
Project-URL: Documentation, https://github.com/NeoResearchAI/MCPServer/blob/main/docs/CLIENTS.md
Project-URL: Bug Tracker, https://github.com/NeoResearchAI/MCPServer/issues
Keywords: mcp,ai,ml,neo,llm,claude
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.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: mcp>=1.26.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: anyio>=4.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"

# neo-mcp

Python MCP server for [Neo](https://heyneo.so) — submit AI/ML tasks, poll status, read output, and control task lifecycle from any AI editor.

The server runs locally over stdio. On first task submission it auto-starts the npm daemon (`npx neo-mcp-daemon`) to handle local file execution. A Python daemon fallback is built in for environments where Node.js is unavailable.

Get your API key at [app.heyneo.so](https://app.heyneo.so) → Settings → API Keys.

---

## Install

```bash
pip install neo-mcp
```

Requires Python 3.11+.

> **Tip:** use `pipx install neo-mcp` to install in an isolated environment and avoid conflicts with your project's virtualenv.

---

## Connecting to editors

All editors below run `neo-mcp` as a stdio subprocess. Replace `sk-v1-YOUR_KEY` with your actual key.

---

### Claude Code

```bash
claude mcp add --scope user neo \
  -e NEO_SECRET_KEY=sk-v1-YOUR_KEY \
  -- neo-mcp
```

Open a **new Claude Code session** after running this command. Neo tools load at session start.

> **Scope options:** `--scope user` (global, recommended) · `--scope project` (writes `.mcp.json` in current repo) · `--scope local` (this machine only)

Verify the server registered correctly:

```bash
claude mcp list
```

---

### Cursor

Edit `~/.cursor/mcp.json` (create if it doesn't exist):

```json
{
  "mcpServers": {
    "neo": {
      "command": "neo-mcp",
      "env": {
        "NEO_SECRET_KEY": "sk-v1-YOUR_KEY"
      }
    }
  }
}
```

Restart Cursor after editing.

---

### Windsurf

Edit `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "neo": {
      "command": "neo-mcp",
      "env": {
        "NEO_SECRET_KEY": "sk-v1-YOUR_KEY"
      }
    }
  }
}
```

Restart Windsurf after editing.

---

### VS Code (GitHub Copilot)

Requires VS Code 1.99+. Edit `.vscode/mcp.json` in your workspace root:

```json
{
  "servers": {
    "neo": {
      "type": "stdio",
      "command": "neo-mcp",
      "env": {
        "NEO_SECRET_KEY": "sk-v1-YOUR_KEY"
      }
    }
  }
}
```

---

### Zed

Edit `~/.config/zed/settings.json`:

```json
{
  "context_servers": {
    "neo": {
      "source": "custom",
      "command": {
        "path": "neo-mcp",
        "args": [],
        "env": {
          "NEO_SECRET_KEY": "sk-v1-YOUR_KEY"
        }
      }
    }
  }
}
```

---

### Continue.dev

Edit `~/.continue/config.json`:

```json
{
  "mcpServers": [
    {
      "name": "neo",
      "transport": {
        "type": "stdio",
        "command": "neo-mcp",
        "env": {
          "NEO_SECRET_KEY": "sk-v1-YOUR_KEY"
        }
      }
    }
  ]
}
```

---

### OpenAI Codex CLI

Edit `~/.codex/config.json`:

```json
{
  "mcpServers": {
    "neo": {
      "command": "neo-mcp",
      "env": {
        "NEO_SECRET_KEY": "sk-v1-YOUR_KEY"
      }
    }
  }
}
```

---

## Tools

| Tool | Description |
|---|---|
| `neo_submit_task` | Submit an AI/ML task. Returns `thread_id` immediately. |
| `neo_list_tasks` | List running and recent tasks — reconnects pollers automatically. |
| `neo_task_status` | Check status: RUNNING / COMPLETED / WAITING_FOR_FEEDBACK / PAUSED / TERMINATED. |
| `neo_get_messages` | Read full task output when COMPLETED. Capped at ~20 000 tokens. |
| `neo_send_feedback` | Reply when Neo asks a question (WAITING_FOR_FEEDBACK). |
| `neo_pause_task` | Pause a running task. |
| `neo_resume_task` | Resume a paused task. |
| `neo_stop_task` | Stop and clean up a task permanently. |

---

## Daemon management

The MCP server auto-starts the npm daemon on first task submission. To start it manually:

```bash
# npm daemon (recommended — Node.js required)
NEO_SECRET_KEY=sk-v1-YOUR_KEY npx --yes neo-mcp-daemon /path/to/workspace &

# Python daemon (fallback — no Node.js needed)
NEO_SECRET_KEY=sk-v1-YOUR_KEY neo-mcp daemon
```

Check daemon status:

```bash
neo-mcp status
neo-mcp doctor
neo-mcp logs --source daemon --lines 50
```

---

## Setup wizard

Auto-configure all supported editors in one step:

```bash
neo-mcp setup
```

Flags:

| Flag | Description |
|---|---|
| `--secret-key KEY` | Skip interactive key prompt |
| `--editor EDITORS` | Comma-separated: `claude,cursor,windsurf,zed,vscode,continue,codex` |
| `--scope SCOPE` | Claude Code scope: `user` (default), `project`, or `local` |
| `--no-backup` | Skip `.bak` backups when overwriting existing configs |

Example:

```bash
neo-mcp setup --secret-key sk-v1-... --editor claude,cursor
```

---

## Environment variables

| Variable | Required | Description |
|---|---|---|
| `NEO_SECRET_KEY` | **Yes** | Your Neo API key (`sk-v1-...`) from [app.heyneo.so](https://app.heyneo.so) |
| `NEO_DEPLOYMENT_ID` | No | Pin a specific deployment UUID (auto-generated and persisted by default) |
| `NEO_WORKSPACE_DIR` | No | Override working directory (useful in Docker) |
| `NEO_READ_ONLY` | No | `true` — expose only status/message tools, disable submit/stop/pause |

---

## Troubleshooting

| Symptom | Fix |
|---|---|
| `neo-mcp: command not found` | Re-run `pip install neo-mcp`; check `which neo-mcp` and verify your PATH |
| Tools don't appear after registering | Open a **new session** — MCP tools load at session start, not mid-session |
| `Invalid API key` (401) | Re-check your key at app.heyneo.so → Settings → API Keys |
| `Trial or quota ended` (403) | Top up at the Neo dashboard |
| Task submitted but no files written | Daemon failed to start — run `NEO_SECRET_KEY=sk-v1-... npx --yes neo-mcp-daemon /workspace &` manually |
| Status stuck on RUNNING | Daemon stopped mid-task — restart it and call `neo_task_status` to check |
