PocketFlow Template Python FastMCP
Pocket Flow Project Template with FastMCP
Ask AI about PocketFlow Template Python FastMCP
Powered by Claude Β· Grounded in docs
I know everything about PocketFlow Template Python FastMCP. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
PocketFlow Template with FastMCP Integration
This is a project template for Agentic Coding with PocketFlow, a 100-line LLM framework, enhanced with FastMCP client integration for accessing Model Context Protocol (MCP) servers.
π Features
- PocketFlow Integration: Build LLM workflows with the minimalist PocketFlow framework
- FastMCP Client: Connect to and use MCP servers for extended functionality
- Docker Support: Complete containerized development environment
- Test-Driven Development: Comprehensive test suite with pytest
- Multiple MCP Servers: Pre-configured support for filesystem, fetch, browser, and more
- AI Assistant Rules: Configuration files for various AI coding assistants
ποΈ Architecture
The template provides:
- MCP Configuration Management: JSON-based server configuration with validation
- MCP Service Layer: Async service for managing MCP client connections
- PocketFlow Nodes: Ready-to-use nodes for MCP operations
- Example Flows: Demonstration flows for common MCP use cases
- Comprehensive Testing: Unit and integration tests
π Prerequisites
- Python 3.11+
- Docker and Docker Compose (recommended)
- Node.js and npm (for MCP servers)
- uv (for Python package management)
π Quick Start
1. Clone and Setup
git clone <repository-url>
cd PocketFlow-Template-Python-FastMCP
2. Automated Setup (Recommended)
# Run the setup script to install dependencies and test everything
python setup.py
This will:
- Check Python version compatibility (3.11+ required)
- Check system dependencies (Node.js, npm, Docker)
- Install all Python dependencies
- Run tests to verify installation
3. Manual Setup
# Install Python dependencies
pip install -r requirements.txt
# Test the installation
python test_basic.py
# Run the application
python main.py
4. Docker Development (Alternative)
# Build and run the application
docker-compose up app
# Run tests
docker-compose run test
π§ Configuration
MCP Servers Configuration
Edit config/mcp_servers.json to configure your MCP servers:
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
},
"fetch": {
"command": "uvx",
"args": ["mcp-server-fetch"]
}
}
}
Environment Variables
OPENAI_API_KEY: Your OpenAI API key for LLM callsRUN_MCP_DEMO: Set to "false" to skip MCP demonstration (default: "true")
π§ Troubleshooting
Common Issues
"No module named 'fastmcp'" Error
This means the FastMCP dependency is not installed. Fix with:
# Option 1: Run the setup script
python setup.py
# Option 2: Install manually
pip install -r requirements.txt
# Option 3: Install specific package
pip install fastmcp>=2.12.0
"No module named 'pocketflow'" Error
Install the PocketFlow framework:
pip install pocketflow>=0.0.1
MCP Server Connection Issues
- Ensure Node.js and npm are installed
- Check that MCP server commands are available:
npx @modelcontextprotocol/server-filesystem --version uvx mcp-server-fetch --version - Verify your
config/mcp_servers.jsonconfiguration
Python Version Issues
This template requires Python 3.11+. Check your version:
python --version
If you have an older version, consider using pyenv or conda to install Python 3.11+.
π Usage Examples
Basic MCP Discovery
from flows.mcp_example_flow import run_discovery_flow
# Discover available MCP servers and tools
result = run_discovery_flow()
print(f"Connected servers: {result['mcp_connected_servers']}")
File Operations
from flows.mcp_example_flow import create_mcp_file_operations_flow
shared = {
"mcp_tool_args_list_directory": {"path": "/tmp"}
}
flow = create_mcp_file_operations_flow()
flow.run(shared)
Dynamic Tool Calling
from nodes.mcp_nodes import MCPDynamicToolNode
# Configure dynamic tool call
shared = {
"mcp_dynamic_tool_name": "fetch",
"mcp_dynamic_tool_args": {"url": "https://httpbin.org/json"}
}
node = MCPDynamicToolNode()
result = node.exec(shared)
π§ͺ Testing
The project includes comprehensive tests:
# Run all tests
docker-compose run test
# Run specific test categories
pytest tests/test_mcp_config.py -v
pytest tests/test_mcp_service.py -v
pytest tests/test_mcp_nodes.py -v
# Run with coverage
pytest tests/ --cov=utils --cov=nodes --cov=flows
π Documentation
- FastMCP Integration Guide - Comprehensive guide to using MCP features
- PocketFlow Documentation - Core framework documentation
- FastMCP Documentation - FastMCP client documentation
π οΈ Available MCP Servers
The template includes configuration for popular MCP servers:
- Filesystem: File system operations (list, read, write files)
- Fetch: Web content fetching and HTTP requests
- Browser MCP: Browser automation capabilities
- Sequential Thinking Tools: Advanced reasoning tools
ποΈ Project Structure
βββ config/
β βββ mcp_servers.json # MCP server configuration
βββ docs/
β βββ mcp_integration.md # Integration documentation
βββ flows/
β βββ mcp_example_flow.py # Example MCP flows
βββ nodes/
β βββ mcp_nodes.py # MCP-enabled PocketFlow nodes
βββ tests/
β βββ test_mcp_config.py # Configuration tests
β βββ test_mcp_service.py # Service layer tests
β βββ test_mcp_nodes.py # Node tests
βββ utils/
β βββ mcp_config.py # Configuration management
β βββ mcp_service.py # MCP service layer
β βββ call_llm.py # LLM utility
βββ docker-compose.yml # Docker services
βββ Dockerfile # Application container
βββ main.py # Main application
βββ requirements.txt # Python dependencies
π€ Contributing
- Fork the repository
- Create a feature branch
- Add tests for new functionality
- Ensure all tests pass
- Submit a pull request
π AI Assistant Configuration
We have included rules files for various AI coding assistants:
- .cursorrules for Cursor AI
- .clinerules for Cline
- .windsurfrules for Windsurf
- .goosehints for Goose
- Configuration in .github for GitHub Copilot
- CLAUDE.md for Claude Code
- GEMINI.md for Gemini
π Learning Resources
π License
This project is licensed under the MIT License - see the LICENSE file for details.
