# Open Science MCP

[简体中文](README.zh-CN.md)

Control the local [Open Science](https://github.com/aipoch/open-science) research application from an MCP client. Create projects, start or continue research, inspect progress and plans, cancel runs, and read generated artifacts. Projects and sessions use Open Science's existing storage and execution engine.

This is an independent integration, inspired by [blender-mcp](https://github.com/ahujasid/blender-mcp). It is not an official AIPOCH project. The server uses local **stdio MCP → authenticated loopback HTTP → Open Science**. Models, research tools, approvals, and compute environments remain managed by Open Science.

## Requirements

- Node.js **22.5 or later**; CI targets Node 22 and 24.
- Open Science desktop application; the compatibility baseline is **v0.29.0**.
- A running local Open Science web service, plus a configured Agent runtime and model provider for research execution.
- An MCP client supporting local stdio servers.

See the [current acceptance report](docs/acceptance-report.md), [compatibility](docs/compatibility.md) and the [acceptance procedure](docs/acceptance.md). Automated contract tests and live application acceptance are separate checks; passing the former does not prove a configured model or a successful research run.

## Install and start

```bash
git clone https://github.com/imjszhang/open-science-mcp.git
cd open-science-mcp
npm ci
npm run build
```

Install Open Science from its [official releases](https://github.com/aipoch/open-science/releases), configure the runtime and provider in the application, and enable/start its local service. When the application CLI is installed:

```bash
open-science start --no-open
open-science doctor --json
node dist/index.js doctor
```

The MCP `doctor` command prints a credential-free report and exits with code 1 if the service is unavailable or runtime/provider readiness is false. It does not start the application or change settings. See [setup](docs/setup.md) for the bundled CLI invocation before an `open-science` launcher exists.

The documented installation is from GitHub source or a release tarball. npm publication is separate; do not assume this package is available from the npm registry.

## Connect an MCP client

Add a local stdio server to your client's MCP configuration, replacing both paths with absolute paths on your computer:

```json
{
  "mcpServers": {
    "open-science": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/open-science-mcp/dist/index.js"]
    }
  }
}
```

The surrounding configuration format varies by client; the server command and arguments are the same. On Windows, JSON paths can use forward slashes, such as `C:/Program Files/nodejs/node.exe`. Use the client's documented configuration location.

Service discovery checks `~/.open-science-project`, then `~/.open-science`, accepting only an authenticated healthy local service. To select one profile explicitly, append `--config-root` and its absolute directory to `args`, or set `OPEN_SCIENCE_CONFIG_ROOT`. See [discovery and credentials](docs/setup.md#discovery-and-credentials).

First ask the client: **“Use Open Science to check readiness and list my projects.”** A running stdio server normally waits silently; stdout is reserved for MCP messages. Diagnostics go to stderr.

## Tools

| Tool | Purpose | Main inputs |
| --- | --- | --- |
| `get_status` | Connection and runtime/provider readiness | None |
| `list_projects` | Project names and stable IDs | None |
| `create_project` | Create a project | `name`, `idempotency_key`; optional `description`, `agent_context` |
| `list_sessions` | Session summaries | Optional `project_id` |
| `get_session` | Summary and current waiting state | `session_id` |
| `start_run` | Start research or continue a session | `project_id`, `prompt`, `idempotency_key`; optional `session_id`, `cwd`, `turn_intent` |
| `get_run` | Status, output, attention, artifacts | `run_id` |
| `wait_run` | Bounded polling | `run_id`; optional `timeout_ms` (default 10,000; maximum 30,000) |
| `cancel_run` | Explicitly cancel a run | `run_id` |
| `get_plan` | Plan and approval state | `session_id` |
| `list_artifacts` | Finalized artifact metadata and resource URIs | `session_id` |
| `read_artifact` | Text/image preview or file download | `session_id`, `artifact_id`; optional `offset`, `max_bytes`, `output_path` |

`create_project` and `start_run` require an `idempotency_key`. Generate a new key once per intended action, for example a UUID. Open Science keeps replay records **in memory for 24 hours from the first request, within the same daemon lifetime**. Within that window and the same instance, retry an uncertain result with the same key and identical arguments. A restart, a different instance, or expiry removes that duplicate protection: inspect the original project/session/run IDs and application UI before deciding whether to retry. Never blindly resubmit or generate a fresh key because a response was lost. A different intended action needs a different key. The server does not automatically retry mutations. Cancellation is scoped to the existing run ID and does not take a key.

Use project and session **IDs**, not names. `get_session` is a summary, not a conversation transcript. A follow-up uses the original `session_id` and the same canonical working directory. Omit `cwd` unless you need a specific existing directory. `turn_intent: "plan-first"` asks Open Science to plan before execution.

Research may use the model provider configured in the app. Approvals and permission requests are handled in the Open Science UI. The server preserves application permission defaults; it does not expose an approval bypass.

## Waiting and results

Run statuses are `running`, `completed`, `failed`, and `cancelled`. Session waiting states are separate. `wait_run` returns a `reason` of `terminal`, `attention`, or `timeout`, with its latest run snapshot and a session snapshot when available. Inspect `run.attention` even on a terminal run. Reaching a wait deadline or closing an MCP request does not cancel accepted research; call `cancel_run` explicitly. If cancellation times out while draining, inspect that same run again.

Text previews use byte windows: `max_bytes` defaults to 65,536 and is capped at 262,144. Continue with the returned `next_offset`. Small PNG/JPEG/WebP/GIF images can be returned inline. Other files, or images too large for inline content, return an `open-science://sessions/{sessionId}/artifacts/{artifactId}` resource link.

To save a complete file up to **100 MiB**, pass an absolute `output_path` with an existing parent directory and `offset: 0`. The destination must not exist; it is opened exclusively and never overwritten. A SHA-256 is returned and checked against artifact metadata when a checksum is available. See [CSV example](examples/csv-analysis/README.md).

## Development

```bash
npm ci
npm run check
npm test
npm pack
```

Tests use an independent local HTTP fixture and a real stdio MCP client; they require no model account. CI also installs the packed package into a clean directory and verifies tool discovery. Live validation uses the [acceptance checklist](docs/acceptance.md).

- [Architecture and boundaries](docs/architecture.md)
- [Setup and service discovery](docs/setup.md)
- [Troubleshooting](docs/troubleshooting.md)
- [Compatibility](docs/compatibility.md)
- [Changes](CHANGELOG.md)

## License and credits

Apache-2.0; see [LICENSE](LICENSE) and [NOTICE](NOTICE). Public task contracts and discovery behavior are adapted from AIPOCH Open Science. blender-mcp inspired the external-adapter-to-live-application architecture; no Blender code is included.