Metadata-Version: 2.4
Name: neo-mcp
Version: 0.2.0
Summary: MCP server for the Neo AI/ML backend — submit tasks, poll status, read output
License-Expression: 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/neo-mcp/docs/SETUP.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: 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
Provides-Extra: http
Requires-Dist: starlette>=0.40.0; extra == "http"
Requires-Dist: uvicorn>=0.30.0; extra == "http"
Requires-Dist: anyio>=4.0.0; extra == "http"

# Neo MCP Server

Run AI/ML tasks on Neo's remote backend directly from Claude Code, Cursor, Windsurf, Zed, VS Code, Continue.dev, and OpenAI Codex CLI.

---

## Quickstart

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

The setup wizard detects your editors, prompts for your Neo secret key, and writes all config files automatically.

---

## No-install option — hosted endpoint

Point any MCP client directly at the hosted server:

| Field | Value |
|---|---|
| URL | `https://mcp.heyneo.so/mcp` |
| Header | `Authorization: Bearer sk-v1-...` |

Get your key from the **Neo dashboard**.

---

## What you need

- Neo account with a secret key (`sk-v1-...`)
- Python 3.11+ **or** Docker

No VS Code extension required for task submission and tracking.

---

## What Neo is for

Neo runs AI/ML work on a remote backend so it does not block your local machine:

- Training or fine-tuning models (classification, regression, NLP, computer vision)
- Building AI agents and multi-agent workflows
- RAG pipelines and vector search systems
- LLM integrations and prompt engineering pipelines
- ML data preprocessing and feature engineering

For general coding your assistant works locally — it only routes to Neo for AI/ML tasks.

---

## Example session

```
You:       "Train a fraud detection model on fraud.csv"
Assistant: Submitting to Neo…
           ⏳ Step 1: Load and preprocess fraud.csv
           ⏳ Step 2: Train XGBoost with cross-validation
           ✅ Step 3: Evaluate — AUC-ROC: 0.94
           Done. Model saved to fraud_model.pkl
```

---

## Available tools

| Tool | Description |
|---|---|
| `neo_submit_task` | Submit an AI/ML task. Returns a `thread_id`; background polling tracks progress. Supports `wait_for_completion=true` to block and return output directly for short tasks. |
| `neo_task_plan` | Show Neo's live step-by-step execution plan with per-step status, result summaries, and file paths. Use while RUNNING instead of fetching full messages. |
| `neo_task_status` | Check overall task status: RUNNING, WAITING_FOR_FEEDBACK, PAUSED, COMPLETED, TERMINATED. |
| `neo_get_messages` | Read the full conversation output once the task is COMPLETED. |
| `neo_send_feedback` | Reply to Neo when it 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. |

---

## How it works

```
neo_submit_task
      │
      ├─ POST /v2/thread/init-chat-direct  →  thread_id
      │         (deployment_type: vscode)
      │
      └─ background poller starts
              │
              ├── GET /v2/thread/status/{thread_id}   (every 3–15 s)
              │         stores status + plan steps in memory
              │
              └── GET /v2/thread/thread-messages      (on COMPLETED)
                        cached for neo_get_messages
```

All polling uses `thread_id` — works with `NEO_SECRET_KEY` auth only. No OAuth required.

---

## Manual registration (Claude Code)

```bash
# Local — pip (recommended)
claude mcp add --scope user neo \
  -e NEO_SECRET_KEY=sk-v1-... \
  -- neo-mcp

# Remote — hosted endpoint (no local install)
claude mcp add --transport http neo https://mcp.heyneo.so/mcp \
  --header "Authorization: Bearer sk-v1-..."
```

See [docs/CLIENTS.md](docs/CLIENTS.md) for all editors.

---

## Configuration

| Variable | Required | Description |
|---|---|---|
| `NEO_SECRET_KEY` | **Yes** | Secret key (`sk-v1-...`) — sole auth token |
| `NEO_API_KEY` | No | Legacy access key, not used for auth |
| `NEO_DEPLOYMENT_ID` | No | Pin a specific VS Code extension deployment ID |
| `NEO_READ_ONLY` | No | `true` = expose only status/plan/message tools |
| `NEO_WORKSPACE_DIR` | No | Override working directory (useful in Docker) |

---

## Troubleshooting

| Symptom | Fix |
|---|---|
| `Invalid API key` (401) | Re-check `NEO_SECRET_KEY` |
| `Trial or quota ended` (403) | Top up at Neo dashboard |
| Task submitted but no files written locally | Requires VS Code/Cursor extension running locally with an active daemon |
| `neo-mcp` command not found | Re-run `pip install neo-mcp` and check your PATH |
| Output truncated | Cap is ~20 000 tokens — use `neo_task_plan` for a concise summary |
| Status stuck on RUNNING | Call `neo_task_plan` to see which step is blocked |
