Metadata-Version: 2.5
Name: frootai-orchard-mcp
Version: 0.1.1
Summary: Model Context Protocol (MCP) server for the FAI Harvest pipeline. Exposes 9 tools (discover_repo / extract_facts / retrieve_exemplars / list_plays / import_accelerator / customize_play / re_harvest / approve_play / list_pending_reviews) over stdio. Run any AI accelerator repo through harvest from Copilot / Cursor / Claude Desktop / Continue / Zed. Byte-equal wire contract with frootai-orchard-mcp (npm).
Project-URL: Homepage, https://frootai.dev/docs/mcp/orchard
Project-URL: Repository, https://github.com/frootai/frootai-core
Project-URL: Issues, https://github.com/frootai/frootai-core/issues
Author-email: FrootAI <hello@frootai.dev>
License: MIT
Keywords: ai-agents,claude,continue,copilot,cursor,frootai,harvest,infrastructure-as-code,mcp,model-context-protocol,orchard,solution-plays,zed
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Provides-Extra: sdk
Requires-Dist: mcp>=1.0.0; extra == 'sdk'
Description-Content-Type: text/markdown

<p align="center"><img src="https://frootai.dev/img/frootai-mark.png" width="80" alt="FrootAI mark"></p>
<h1 align="center">FAI Orchard Harvest MCP for Python</h1>
<p align="center"><strong>A Python, zero-runtime-dependency MCP surface for the governed Harvest pipeline.</strong></p>
<p align="center"><a href="https://pypi.org/project/frootai-orchard-mcp/">PyPI</a> · <a href="https://frootai.dev/orchard">FAI Orchard</a> · <a href="https://frootai.dev/mcp?view=start">MCP guide</a></p>

![FAI Orchard Harvest product hero](https://frootai.dev/images/package-readmes/orchard-hero.png)

## Catalog or Harvest?

| Need | Package |
|---|---|
| Read published accelerator catalog records | Orchard catalog source package `frootai-mcp-orchard` |
| Run repository discovery, extraction, retrieval, import, customization, or approval | **`frootai-orchard-mcp`** — this package |

Current version `0.1.1` is an early Harvest MCP surface. Confirm which handlers your installed release registers before relying on a specific pipeline operation.

> Current registry truth: the tool registry declares nine handlers, including `list_pending_reviews`. The `0.1.1` CLI help banner still says eight; treat `tools/list` as authoritative until that banner is corrected in a future code release.

## Five steps

### 1. Install or run in isolation

```bash
uvx frootai-orchard-mcp
```

Or install into a managed Python 3.10+ environment:

```bash
python -m pip install --upgrade "frootai-orchard-mcp[sdk]"
```

### 2. Connect an MCP client

```json
{
  "servers": {
    "frootai-orchard-harvest": {
      "type": "stdio",
      "command": "uvx",
      "args": ["frootai-orchard-mcp"]
    }
  }
}
```

### 3. Discover, extract, and retrieve

```text
discover_repo → extract_facts → retrieve_exemplars → list_plays
```

These free operations establish source identity and structured evidence before any import or customization.

### 4. Import and customize with entitlement

```text
import_accelerator → customize_play → re_harvest
```

Import and drift operations require eligible entitlements. Policy overlays and three-way diffs must remain reviewable; no entitlement implies blanket approval to overwrite a target.

### 5. Separate generation from approval

`list_pending_reviews` is reviewer-gated. `approve_play` is founder-gated. Keep candidate generation, review, and final promotion as separate identities and operations.

<details open>
<summary><strong>See the governed Orchard lifecycle</strong></summary>

![Orchard builds, FAI Engine verifies, and Lab publishes evidence](https://frootai.dev/images/package-readmes/orchard-lifecycle.png)

Open the live [FAI Orchard product lifecycle](https://frootai.dev/orchard).

</details>

## Nine-tool surface

<details open>
<summary><strong>Expand the Harvest pipeline tools and access boundaries</strong></summary>

| Tool | Access | Purpose |
|---|---|---|
| `discover_repo` | Free | Resolve and classify a source repository |
| `extract_facts` | Free | Extract structured architecture and IaC facts |
| `retrieve_exemplars` | Free | Find canonical reference Plays |
| `list_plays` | Free | Browse the slim Play catalog |
| `import_accelerator` | Pro / `import` | Run import and return signed artifact evidence |
| `customize_play` | Pro / `upgrade-to-play` | Apply organization policy and return a reviewable diff |
| `re_harvest` | Pro / `import` | Re-run at an updated source revision and report drift |
| `list_pending_reviews` | Reviewer | List candidates awaiting governance review |
| `approve_play` | Founder | Promote an authorized candidate |

</details>

## Embed with injected services

```python
from frootai_orchard_mcp import TOOL_NAMES, create_server, run_stdio

server = create_server(
    services={
        # Inject repository, extraction, retrieval, artifact,
        # identity, telemetry, and governance adapters.
    }
)

print(TOOL_NAMES)
run_stdio(server)
```

The core is standard-library based and designed for hermetic testing. Missing service capabilities must return explicit errors rather than synthetic success.

## Protocol resources and prompts

The Harvest surface exposes `frootai://plays`, `frootai://policy-schema`, `frootai://auth/device`, and `frootai://exemplars/{id}`. Guided prompts are `import-rag`, `import-agent`, `customize-for-my-company`, and `audit-existing-infra`. Prompts prefill instructions and never invoke tools on their own.

## Transport options

```bash
# Stdio — default
uvx frootai-orchard-mcp

# Streamable HTTP + SSE
uvx frootai-orchard-mcp --http --port 8080

# Inspect without starting
uvx frootai-orchard-mcp --version
uvx frootai-orchard-mcp --help
```

The Python `0.1.1` CLI does not advertise the npm server's `--ws` option. Do not assume WebSocket parity; query the selected runtime's help and MCP capabilities.

## Safety boundaries

- Stdio is the smallest default process boundary.
- `FROOTAI_TOKEN` and local identity state are resolved without returning raw credentials.
- Treat source repositories and generated instructions as untrusted inputs.
- Bind evidence to source revision, artifact identity, policy overlay, and approval receipt.
- Validate generated infrastructure independently before deployment.
- Keep reviewer/founder operations separate from automated import identities.

## Verify and develop

Build the package and run repository-level Orchard/Harvest protocol and service-adapter tests. Every injected adapter should cover denial, timeout, malformed data, partial failure, retry, and rollback behavior.

## Links

- [FAI Orchard](https://frootai.dev/orchard)
- [FAI Engine verification](https://frootai.dev/fai-engine)
- [PyPI package](https://pypi.org/project/frootai-orchard-mcp/)
- [npm mirror](https://www.npmjs.com/package/frootai-orchard-mcp)
- [Issues](https://github.com/frootai/frootai-core/issues)

## License

MIT © 2026 FrootAI.
