# Wanatux Labs MCP

An [MCP](https://modelcontextprotocol.io) server for the **Open Science Framework (OSF)**.
Point any MCP client at it and ask about a research project by its OSF id.

No credentials. No accounts. It reads the public OSF API and returns structured JSON.

```
osf.io/bvy3q  ->  "From Automation to Agency: Observations from a
                   Local-First, Conversational Personal Systems Lab"
                   10 components, 8 tags, public since 2025-12-26
```

## Use the hosted server

Nothing to install — add this URL to any MCP client that supports remote servers:

```
https://labs.wanatux.net/mcp
```

For Claude Code:

```bash
claude mcp add --transport http wanatux-labs https://labs.wanatux.net/mcp
```

The hosted instance is rate limited to 60 requests/minute per IP.

## Or run it yourself

```bash
pip install git+https://github.com/jayala-wt/wanatux-labs-mcp
wanatux-labs-mcp            # serves on :8101, override with WANATUX_MCP_PORT
```

## Tools

| Tool | Returns |
|---|---|
| `osf_get_project(project_id)` | Title, category, description, tags, dates, public flag, URL |
| `osf_get_abstract(project_id)` | Just the abstract text, plus a `has_abstract` flag |
| `osf_list_components(project_id)` | Child components with ids, titles, categories, URLs |

All three are read-only and idempotent. `project_id` is the short code in an OSF URL —
`https://osf.io/bvy3q/` → `bvy3q`. A full OSF URL is accepted too, so pasting works.

### Example

```jsonc
// osf_list_components("bvy3q")
{
  "ok": true,
  "project_id": "bvy3q",
  "count": 10,
  "components": [
    {
      "id": "uf5hn",
      "title": "[Core] Defining the Epistemic Activation Problem: Interim Findings (v0.2.0)",
      "category": "project",
      "public": true,
      "url": "https://osf.io/uf5hn/"
    }
  ],
  "truncated": false
}
```

Errors are returned as data, never as exceptions:

```jsonc
{ "ok": false, "error": "No such OSF project (it may be private or the id may be wrong)" }
```

## Design

The server is meant to be reachable by anyone, so one rule governs every tool:

> **Public data in, public data out.** No credentials, no local filesystem, no private
> data, no shell.

Practically that means:

- **No auth, deliberately.** There is nothing to protect — every byte it returns is
  already public on osf.io.
- **Rate limited per IP**, honoring `CF-Connecting-IP` behind a proxy.
- **Responses carry no provenance.** No hostnames, no file paths, no command lines. A
  public server that echoes its own internals is a public server that leaks.
- **Upstream responses cached** for 120s, so a client in a loop doesn't turn into a
  denial-of-service against OSF.
- **Timeouts on every upstream call**, and upstream failures become clean `ok: false`
  results rather than tracebacks.

## Related

[paperclip](https://github.com/matsjfunke/paperclip) searches *papers* across Arxiv, OSF
and OpenAlex. This server does something different: it inspects an OSF *project* — its
metadata, abstract, and component tree. If you want to find papers, use paperclip. If you
have a project id and want to know what's in it, use this.

## License

MIT — see [LICENSE](LICENSE).