Metadata-Version: 2.4
Name: frootai-mcp
Version: 6.1.2
Summary: FrootAI MCP Server — 62 tools, 4 resources, 6 prompts, 101 plays, 863+ primitives. FastMCP-powered Python implementation of the FAI Engine.
Author-email: Pavleen Bali <pavleenbali@frootai.dev>
License: MIT
Project-URL: Homepage, https://frootai.dev
Project-URL: Repository, https://github.com/frootai/frootai
Project-URL: Documentation, https://frootai.dev/setup-guide
Project-URL: Bug Tracker, https://github.com/frootai/frootai/issues
Keywords: mcp,ai,architecture,azure,copilot,claude,frootai,agents
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp[cli]<2.0.0,>=1.9.0

<p align="center"><img src="https://frootai.dev/img/frootai-mark.png" width="88" alt="FrootAI mark"></p>
<h1 align="center">FrootAI MCP for Python</h1>
<p align="center"><strong>Give MCP-compatible agents a local Python process with 62 FrootAI tools, 4 resources, 6 prompts, and trust-gated federation.</strong></p>
<p align="center">
  <a href="https://pypi.org/project/frootai-mcp/"><img src="https://img.shields.io/pypi/v/frootai-mcp?style=flat-square&logo=python" alt="PyPI version"></a>
  <a href="https://pypi.org/project/frootai-mcp/"><img src="https://img.shields.io/pypi/dm/frootai-mcp?style=flat-square&label=downloads" alt="PyPI downloads"></a>
  <a href="https://www.python.org"><img src="https://img.shields.io/pypi/pyversions/frootai-mcp?style=flat-square" alt="Python versions"></a>
  <a href="https://opensource.org/license/mit"><img src="https://img.shields.io/badge/license-MIT-f2c94c?style=flat-square" alt="MIT license"></a>
</p>
<p align="center"><a href="https://frootai.dev/python">Python product page</a> · <a href="https://frootai.dev/setup-guide#python">Setup guide</a> · <a href="https://pypi.org/project/frootai-mcp/">PyPI</a> · <a href="https://frootai.dev/mcp">MCP guide</a></p>

![Choose the FrootAI Python SDK or Python MCP server](https://frootai.dev/images/package-readmes/python-mcp.png)

## Choose Python MCP or the SDK

| Use | Choose |
|---|---|
| VS Code, Claude, Cursor, or another MCP client should call FrootAI tools | **FrootAI MCP for Python** — this package |
| Python application code needs direct method calls and return values | [`frootai`](https://pypi.org/project/frootai/) SDK |

Python MCP runs locally over stdio. Installing it does not start a daemon, publish an endpoint, deploy cloud resources, or grant a client blanket permission to modify files.

## Five steps to first value

### 1. Install and verify

```bash
python -m pip install --upgrade frootai-mcp
frootai-mcp-py
```

Requirements: Python 3.10 or newer. Press `Ctrl+C` after confirming that the server starts; an MCP client normally owns the process lifecycle.

### 2. Connect an MCP client

VS Code and GitHub Copilot — `.vscode/mcp.json`:

```json
{
  "servers": {
    "frootai-python": {
      "type": "stdio",
      "command": "frootai-mcp-py"
    }
  }
}
```

Claude Desktop or Cursor:

```json
{
  "mcpServers": {
    "frootai-python": {
      "command": "frootai-mcp-py"
    }
  }
}
```

If the executable is not on `PATH`, use the absolute path from the same Python environment in which the package was installed.

### 3. Ask for grounded discovery

```text
Search FrootAI knowledge for secure RAG patterns.
Find the best two Solution Plays, compare them,
and show the relevant WAF security guidance.
```

A typical sequence is:

```text
search_knowledge → semantic_search_plays → compare_plays
                 → get_play_detail → get_waf_guidance
```

### 4. Wire, scaffold, and evaluate

```text
wire_play → validate_manifest → preview_scaffold
          → evaluate_quality → agent_review → agent_tune
```

Use preview and validation before any write-oriented operation. `wire_play`, `scaffold_play`, `smart_scaffold`, and live evaluation expose their operating boundary through MCP annotations and return values.

### 5. Use the server from Python when needed

```python
from frootai_mcp.server import mcp

mcp.run(transport="stdio")
```

Tools are async Python functions and can also be called directly:

```python
import asyncio
from frootai_mcp.server import search_knowledge, wire_play

async def main() -> None:
    results = await search_knowledge(query="RAG architecture")
    manifest = await wire_play("01")
    print(results)
    print(manifest)

asyncio.run(main())
```

For application-level APIs rather than an MCP server process, prefer the [`frootai`](https://pypi.org/project/frootai/) SDK.

<details open>
<summary><strong>See the shared Python decision workflow</strong></summary>

![Search, inspect, evaluate, and choose an in-process SDK or MCP boundary](https://frootai.dev/images/package-readmes/python-sdk.png)

Open the live [Python SDK and MCP comparison](https://frootai.dev/python).

</details>

## Capability map — 62 tools

<details open>
<summary><strong>Knowledge, Plays, architecture, models, and cost</strong></summary>

| Area | Tools |
|---|---|
| Knowledge | `list_modules`, `get_module`, `search_knowledge`, `lookup_term`, `get_architecture_pattern`, `get_froot_overview` |
| Lean/full content | `fai_lean`, `fai_full` |
| Solution Plays | `list_solution_plays`, `get_play_detail`, `semantic_search_plays`, `compare_plays`, `generate_architecture_diagram` |
| Models and cost | `get_model_catalog`, `get_azure_pricing`, `compare_models`, `estimate_cost` |
| Ecosystem | `get_github_agentic_os`, `list_community_plays`, `fetch_azure_docs`, `fetch_external_mcp`, `get_play_spec` |

Bundled knowledge is offline-capable. Live-reference and pricing outputs may rely on packaged snapshots or external availability; treat cost as directional.

</details>

<details>
<summary><strong>Build, review, FAI Engine, and evaluation</strong></summary>

| Area | Tools |
|---|---|
| Agent chain | `agent_build`, `agent_review`, `agent_tune` |
| FAI Engine | `wire_play`, `inspect_wiring`, `validate_manifest`, `validate_config`, `evaluate_quality` |
| Evaluation | `run_evaluation`, `run_eval_live`, `prompt_dry_run`, `embedding_playground` |
| Workspace | `analyze_workspace` |
| Guidance | `get_bicep_best_practices`, `get_waf_guidance`, `check_play_compatibility`, `get_learning_path`, `export_play_config`, `get_version_info` |

Live evaluation requires an endpoint supplied by the caller. Prompt dry-run can use configured provider access or a deterministic fallback; its checks do not replace production evaluation.

</details>

<details>
<summary><strong>Scaffolding and marketplace</strong></summary>

| Area | Tools |
|---|---|
| Project scaffold | `scaffold_play`, `smart_scaffold`, `list_templates`, `preview_scaffold`, `scaffold_status` |
| Components | `scaffold_component`, `get_play_config`, `get_dependencies`, `generate_bicep` |
| Primitives | `list_primitives`, `list_marketplace`, `get_primitive_detail`, `search_marketplace` |

Use `preview_scaffold` before creating files. Generated Bicep is source output for review and validation; it is not an automatic deployment.

</details>

<details>
<summary><strong>Trust-gated federation</strong></summary>

`marketplace_spec`, `trust_evidence`, `fai_discover_mcp`, `fai_trust_query`, `fai_attach_mcp`, `fai_list_attached`, `fai_invoke_via`, and `fai_detach_mcp` provide local external-area discovery and routing.

Review the requested server package, publisher, credentials, transport, tool annotations, and destructive capabilities before attach. Use qualified names and detach when the area is no longer needed.

</details>

<details>
<summary><strong>Complete 62-tool reference</strong></summary>

| Tool | Purpose |
|---|---|
| `trust_evidence` | Inspect bundled trust evidence for a publisher or package |
| `marketplace_spec` | Read a Tier-1 external-area attach specification |
| `list_modules` | List packaged FROOT knowledge modules |
| `get_module` | Read a module or selected section |
| `fai_lean` | Fetch a fidelity-checked compact FAI primitive |
| `fai_full` | Fetch the full source form of a FAI primitive |
| `search_knowledge` | Search packaged knowledge with BM25 ranking |
| `lookup_term` | Resolve an AI/ML glossary term |
| `get_froot_overview` | Explain FROOT layers and package scope |
| `get_architecture_pattern` | Return guidance for a supported architecture scenario |
| `list_solution_plays` | Browse packaged Solution Plays with filters |
| `get_play_detail` | Read a Play's services, tuning, and DevKit guidance |
| `semantic_search_plays` | Match natural language to Solution Plays |
| `compare_plays` | Compare architecture, services, and complexity |
| `generate_architecture_diagram` | Render a Play as Mermaid architecture source |
| `agent_build` | Produce Play-aware architecture and implementation guidance |
| `agent_review` | Review supplied code or configuration for actionable issues |
| `agent_tune` | Validate tuning parameters and readiness blockers |
| `get_model_catalog` | Browse model metadata and scenario guidance |
| `get_azure_pricing` | Return directional Azure service pricing data |
| `compare_models` | Compare models for a stated task and priority |
| `estimate_cost` | Produce a directional Play cost breakdown |
| `get_github_agentic_os` | Explain `.github` Agentic OS primitives |
| `list_community_plays` | Browse community Solution Play references |
| `fetch_azure_docs` | Retrieve relevant Microsoft Learn references |
| `fetch_external_mcp` | Discover external MCP servers from configured public sources |
| `get_play_spec` | Read a Play's SpecKit and WAF alignment |
| `wire_play` | Resolve a Play's FAI manifest graph |
| `inspect_wiring` | Explain resolved agents, skills, instructions, and hooks |
| `validate_manifest` | Validate FAI manifest structure and references |
| `validate_config` | Validate TuneKit-style configuration values |
| `analyze_workspace` | Inspect an explicit workspace root and report gaps |
| `evaluate_quality` | Apply Play-aware quality guardrails to supplied scores |
| `list_marketplace` | Browse packaged primitives by marketplace type |
| `get_primitive_detail` | Read one primitive's marketplace detail |
| `search_marketplace` | Search packaged primitive metadata |
| `embedding_playground` | Compare text similarity with the available backend |
| `scaffold_play` | Create or preview a Play project structure |
| `smart_scaffold` | Match a description to a Play and scaffold it |
| `list_templates` | List scaffold templates by complexity |
| `preview_scaffold` | Preview scaffold output without writing |
| `scaffold_status` | Inspect generated project completeness |
| `run_evaluation` | Compare supplied scores with configured thresholds |
| `get_bicep_best_practices` | Return Bicep security and reliability guidance |
| `list_primitives` | Browse packaged FAI primitives by type |
| `get_waf_guidance` | Return guidance for one Well-Architected pillar |
| `check_play_compatibility` | Check whether two Plays can compose |
| `get_learning_path` | Return a curated topic learning path |
| `export_play_config` | Export packaged Play configuration |
| `get_version_info` | Report server and capability metadata |
| `scaffold_component` | Generate one supported AI component example |
| `get_play_config` | Return starter configuration for a Play |
| `get_dependencies` | Return language-specific dependency guidance |
| `generate_bicep` | Generate reviewable Bicep source for supported Plays |
| `run_eval_live` | Run test cases against an explicit live endpoint |
| `prompt_dry_run` | Exercise a prompt and return lightweight checks |
| `fai_attach_mcp` | Attach one trust-approved external MCP area |
| `fai_detach_mcp` | Release an attached area's lifecycle |
| `fai_list_attached` | List active areas and qualified tools |
| `fai_discover_mcp` | Discover compatible external MCP areas |
| `fai_trust_query` | Evaluate publisher and package trust policy |
| `fai_invoke_via` | Invoke a qualified tool through an attached area |

</details>

## MCP resources

| URI | Purpose |
|---|---|
| `fai://modules/{module_id}` | Read a FROOT module |
| `fai://plays/{play_id}` | Read a Solution Play |
| `fai://glossary/{term}` | Resolve an AI/ML term |
| `fai://overview` | Inspect the FrootAI and FAI Engine overview |

## MCP prompts

| Prompt | Purpose |
|---|---|
| `design_architecture` | Guided requirements-to-architecture flow |
| `review_config` | Structured production configuration review |
| `pick_solution_play` | Conversational Solution Play selection |
| `estimate_costs` | Directional service and scale estimate |
| `scaffold_project` | Guided project bootstrapping |
| `learn_fai_protocol` | FAI Protocol walkthrough |

## What ships inside

| Component | Purpose |
|---|---|
| Bundled FROOT knowledge | Offline architecture and operating guidance |
| BM25 search index | Deterministic local retrieval over packaged content |
| Solution Play catalog | Reference architectures and tuning metadata |
| AI glossary | Terminology available through tools and resources |
| FAI Engine contracts | Manifest wiring, validation, configuration, and quality evaluation |
| Federation snapshots | Trust, marketplace, lifecycle, and area metadata |

The Python and Node MCP packages currently register the same 62 primary tool names. Transport implementation, packaging, and runtime dependencies differ; treat `tools/list` from the running server as authoritative rather than assuming byte-identical behavior.

<details>
<summary><strong>Common workflows</strong></summary>

```text
search_knowledge → semantic_search_plays → get_play_detail
agent_build → agent_review → agent_tune
wire_play → validate_manifest → evaluate_quality
preview_scaffold → scaffold_play → scaffold_status
fai_discover_mcp → fai_trust_query → fai_attach_mcp
                 → fai_invoke_via → fai_detach_mcp
```

`run_eval_live` returns aggregate and per-case evidence from an explicitly supplied endpoint. `prompt_dry_run` returns a response plus lightweight checks and iteration suggestions. Neither replaces a production evaluation plan.

</details>

## Safety and operating boundaries

| Boundary | Contract |
|---|---|
| Process | Local stdio process launched and stopped by the MCP client |
| Tool metadata | MCP annotations distinguish read-only, open-world, and file-affecting behavior |
| Inputs | Typed FastMCP schemas and bounded arguments reject malformed calls |
| Workspace | Explicit roots and sandbox checks constrain file inspection and scaffold output |
| Federation | Trust evidence is evaluated before attach; credentials remain local |
| Secrets | Provider keys and downstream credentials belong in the process environment or a secret store, never in prompts or committed config |
| Evaluation | Local thresholds and lightweight checks are evidence, not production certification |
| Infrastructure | Generated Bicep requires review, compilation, what-if, approval, and a separate deployment action |

## Verify and develop

```bash
cd python-mcp
python -m pip install --upgrade build pytest
python -m pytest tests -v
python -m build
```

Live provider suites are opt-in and require their documented environment variables.

## Related packages

| Package | Use it when |
|---|---|
| [`frootai` on PyPI](https://pypi.org/project/frootai/) | A Python application or notebook needs direct SDK values |
| [`frootai-mcp` on npm](https://www.npmjs.com/package/frootai-mcp) | A Node.js MCP server or local federation router is preferred |
| [`frootai` on npm](https://www.npmjs.com/package/frootai) | A human or automation needs Agent FAI and Operator CLI |
| [Orchard Harvest MCP](https://pypi.org/project/frootai-orchard-mcp/) | Repository conversion should run through the specialized Python MCP package |

## Links

- [Python product page](https://frootai.dev/python)
- [Python setup](https://frootai.dev/setup-guide#python)
- [FrootAI MCP guide](https://frootai.dev/mcp)
- [FAI Orchard](https://frootai.dev/orchard)
- [Security and trust](https://frootai.dev/security)
- [PyPI package](https://pypi.org/project/frootai-mcp/)
- [Issues](https://github.com/frootai/frootai-core/issues)

## License

MIT © 2026 FrootAI.
