Metadata-Version: 2.4
Name: denario-mcp
Version: 0.7.1
Summary: Local MCP client for Denario — owns local file/git I/O, delegates private research compute to the Cloud Run API.
License-Expression: Apache-2.0
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.0.0
Provides-Extra: test
Requires-Dist: pytest>=8; extra == 'test'
Description-Content-Type: text/markdown

# denario-mcp

A lightweight, local **MCP client** for [Denario](https://denario-web.vercel.app)
— an AI research assistant you drive from Claude. It runs on your machine and
owns all local filesystem + git work; the private research pipeline runs
remotely on Google Cloud Run and only ever returns generated data (text,
PDFs), never source code.

## Why a local client

Running project setup remotely could never create files on your own disk, and
creating a GitHub repo from inside a container would use the *server's*
GitHub identity, not yours. So all file and git work happens locally, under
your own identity — only the confidential research compute itself is remote.

## Install

```bash
pip install denario-mcp
```

Deliberately lightweight: it depends only on `mcp` and `httpx`, not on the
Denario research stack itself — that stays entirely on the server.

`git` and the GitHub CLI (`gh`, signed in via `gh auth login`) are
**optional**. Without them your project is still created and every generated
file is still written to disk — only the git/GitHub side of a few tools is
skipped.

## Use with Claude Code

```bash
claude mcp add denario \
  -e DENARIO_API_KEY=denario_live_your_key_here \
  -e DENARIO_CLOUD_URL=https://denario-mcp-engine-tnf7nmfboa-uc.a.run.app \
  -- denario-mcp
```

Or, editing the MCP config by hand (`~/.claude.json`, or a project's
`.mcp.json`):

```jsonc
{
  "mcpServers": {
    "denario": {
      "command": "denario-mcp",
      "env": {
        "DENARIO_API_KEY": "denario_live_your_key_here",
        "DENARIO_CLOUD_URL": "https://denario-mcp-engine-tnf7nmfboa-uc.a.run.app"
      }
    }
  }
}
```

Get an API key and the full walkthrough at
[denario-web.vercel.app/tutorial](https://denario-web.vercel.app/tutorial).

## Tools

| Tool | Runs | What it does |
|---|---|---|
| `denario_setup` | Local | Creates the project directory, `data_description.md`, and a local git repo with an initial commit. |
| `denario_idea` | Local + remote | Generates a research idea from `data_description.md`. |
| `denario_methods` | Local + remote | Generates the methodology from the data description + idea. |
| `denario_evaluate` | Local + remote | Evaluates an iteration's results and returns a decision: iterate (run `denario_methods` again) or write the paper. |
| `denario_classify` | Local + remote | Classifies the generated paper into arXiv categories. |
| `denario_paper` | Local + remote | Writes the paper and compiles it to PDF (~10 minutes). |
| `denario_publish` | Local | Updates `README.md` from the paper, commits, pushes, and enables GitHub Pages. |
| `denario_status` | Local | Reports which iterations exist and which is most complete. |
| `denario_read_file` | Local | Reads a file from the local project. |
| `denario_list_files` | Local | Lists files in the local project matching a glob pattern. |

Every "local + remote" tool follows the same shape:

```
client (denario-mcp)                          server (Cloud Run)
  read local input file(s)
  POST /v1/compute/<step>  ─────────────────►   run the pipeline in an ephemeral dir
  ◄─────────────────────────────────────────    { artifacts, log[, result] }
  write artifacts into the local project dir
  git commit (and push, if enabled — see below)
```

The server never touches your disk or your git identity; this client owns
both. Long steps (like `denario_paper`) are handled transparently whether the
server runs them synchronously or as an async job it polls to completion —
nothing to configure on your end.

## GitHub integration is opt-in

By default, nothing is pushed to GitHub — every step commits **locally
only**. Set `DENARIO_GITHUB_PUSH=1` to have `denario_setup` create a GitHub
repo under your own identity and have each step push after committing.
`denario_publish` is the one exception: it always pushes, since publishing is
an explicit action regardless of that setting.

## Environment

| Var | Purpose | Default |
|---|---|---|
| `DENARIO_API_KEY` | Bearer token for the remote compute API. | — (required for remote tools) |
| `DENARIO_CLOUD_URL` | Base URL of the compute API. | — (required for remote tools) |
| `DENARIO_GITHUB_PUSH` | Opt in to automatic GitHub repo creation + pushes. | off |
| `GITHUB_ORG` | Org/account for created repos. | `ParallelScience` |
| `SCIENTIST_NAME` | Used in the derived repo slug + README. | `denario` |
| `DENARIO_MCP_LOG` | If set, log file path (keeps logs off stdout, which carries the MCP protocol). | none |
| `DENARIO_MCP_LOG_LEVEL` | Log level. | `INFO` |
| `DENARIO_BUILD_PAGE_SCRIPT` | Optional external script to build a GitHub Pages site for `denario_publish`. | none |
| `DENARIO_LIVE_TEST` | Set to `1` to run the opt-in live smoke test against a real deployment. | unset |

## Development

```bash
pip install -e ".[test]"
python -m pytest -m "not live"
```

That last flag skips the one opt-in test that hits a real deployment
(gated separately by `DENARIO_LIVE_TEST=1`, so it never runs by accident).
