FAI Orchard Harvest MCP for Python

A Python, zero-runtime-dependency MCP surface for the governed Harvest pipeline.

PyPI · FAI Orchard · MCP guide

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

uvx frootai-orchard-mcp

Or install into a managed Python 3.10+ environment:

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

2. Connect an MCP client

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

3. Discover, extract, and retrieve

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

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.

See the governed Orchard lifecycle

Open the live FAI Orchard product lifecycle.

Nine-tool surface

Expand the Harvest pipeline tools and access boundaries

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

Embed with injected services

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

# 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
• FAI Engine verification
• PyPI package
• npm mirror
• Issues

License

MIT © 2026 FrootAI.