francisco-perez-sorrosal/francisco
If you are the rightful owner of francisco and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
Francisco is a Model Context Protocol (MCP) server that features an intelligent AI agent specialized in Python development and self-replication.
Francisco - MCP Server with Agentic AI
Francisco is a Model Context Protocol (MCP) server that exposes an intelligent AI agent specialized in Python development and self-replication. The agent, named Francisco, is designed to assist with creating, improving, and replicating Python projects using modern development practices.
Features
- ๐ค Intelligent AI Agent: Francisco agent specialized in Python development and self-replication
- ๐ง MCP Integration: Simplified FastMCP server implementation
- ๐ Self-Replication: Agent designed to create and improve Python projects
- ๐ฆ Modern Tooling: Built with pixi, Pydantic, loguru, typer, and rich
- ๐งช Comprehensive Testing: Full test suite with pytest
- ๐จ Beautiful CLI: Rich terminal interface with colorful output
- โ๏ธ Configurable: YAML-based agent configuration with template system
- ๐ Easy Integration: FastMCP decorator-based tool registration
Quick Start
Prerequisites
- Python 3.11+
- pixi package manager
- OpenAI API key
Installation
-
Clone and setup the project:
git clone <repository-url> cd francisco
-
Install dependencies with pixi:
pixi install
-
Set your OpenAI API key:
export OPENAI_API_KEY=your_openai_api_key_here
-
Start the MCP server:
pixi run serve
Usage
CLI Commands
Show Version
pixi run cli version
View Agent Configuration
pixi run config
Test Agent
pixi run cli test-agent "Create a simple Python CLI tool"
Start MCP Server
pixi run serve
MCP Tools
When the MCP server is running, it exposes two tools:
invoke
Invoke Francisco agent for Python development and self-replication tasks.
Parameters:
input
(required): The request or task description for Francisco agentcontext
(optional): Additional context information
Example:
{
"input": "Create a Python project for data analysis with pandas and matplotlib",
"context": {
"project_name": "data-analyzer",
"target_directory": "/path/to/project"
}
}
status
Get Francisco agent status and capabilities.
Parameters: None
Example:
{}
Configuration
Environment Variables
Copy env.example
to .env
and configure:
# Francisco Agent Configuration
DEBUG=false
LOG_LEVEL=INFO
APP_NAME=francisco
# OpenAI API Configuration
OPENAI_API_KEY=your_openai_api_key_here
# Agent Configuration
AGENT_NAME=francisco
AGENT_MODEL=gpt-4o
AGENT_MAX_ITERATIONS=10
# Self-replication settings
REPLICATION_TARGET_DIR=replicated_projects
ENABLE_GIT_OPERATIONS=true
ENABLE_GITHUB_OPERATIONS=false
Agent Configuration (francisco.yaml)
The agent's personality, capabilities, and behavior are configured in francisco.yaml
. This file defines:
- Personality traits and communication style
- Core objectives and goals
- Capabilities and supported technologies
- Self-replication strategy and quality standards
- Working principles and interaction guidelines
- Success metrics for evaluating agent performance
- Limitations and boundaries for safe operation
The configuration uses a structured Pydantic model system with individual components:
SuccessMetrics
: Defines measurable success criteriaLimitationsAndBoundaries
: Sets operational constraintsPersonality
,Capabilities
,Strategy
: Modular configuration components
Each component renders to XML format in the agent's prompt template, providing clear structure and easy customization.
Development
Project Structure
francisco/
โโโ src/francisco/ # Main package
โ โโโ __init__.py # Package initialization
โ โโโ agent.py # Francisco agent implementation
โ โโโ agent_models.py # Pydantic models for agent configuration
โ โโโ config/ # Configuration files
โ โ โโโ __init__.py
โ โ โโโ francisco.yaml # Agent configuration
โ โ โโโ francisco_prompt.txt # Agent prompt template
โ โโโ logger.py # Logging configuration
โ โโโ main.py # CLI entry point
โ โโโ mcp_server.py # Simplified FastMCP server implementation
โโโ tests/ # Test suite
โ โโโ __init__.py
โ โโโ test_agent.py
โ โโโ test_logger.py
โ โโโ test_main.py
โโโ francisco.yaml # Root agent configuration
โโโ pyproject.toml # Project configuration with pixi tasks
โโโ README.md # This file
Development Commands
# Install dependencies
pixi install
# Run tests
pixi run test
# Format code
pixi run format
# Lint code
pixi run lint
# Run both lint and test
pixi run check
# Run the CLI (shows help)
pixi run cli
# Start the MCP server
pixi run serve
# Show agent configuration
pixi run config
Testing
The project includes comprehensive tests:
# Run all tests
pixi run test
# Run specific test file
pixi run pytest tests/test_agent.py -v
# Run with coverage
pixi run pytest --cov=src/francisco tests/
Agent Configuration Templates
Francisco's capabilities, personality, and behavior are defined in template files:
Agent Configuration
See for the complete agent configuration including:
- Personality traits and communication style
- Core objectives and goals
- Programming languages and frameworks
- Project types and capabilities
- Working principles and quality standards
- Success metrics and limitations
Agent Prompt Template
The agent's system prompt is defined in , which uses placeholder substitution to incorporate all configuration elements into a structured prompt.
Configuration Model
The file contains the Pydantic models that define the structure and validation for all agent configuration components.
Self-Replication Strategy
Francisco follows a systematic approach to self-replication:
- Analyze existing projects and identify improvement opportunities
- Create new Python projects with modern tooling and best practices
- Establish automated workflows and CI/CD pipelines
- Document and share knowledge through comprehensive README files
- Iterate and improve based on feedback and usage patterns
Quality Standards
- Code is executable and functional
- Code is clean and readable
- Code is maintainable and scalable
- Code is documented and has good comments
- Always use pixi for dependency management
- Implement comprehensive testing with pytest
- Use Pydantic for data validation and configuration
- Follow modern Python packaging standards (PEP 621)
- Include proper logging with loguru
- Create beautiful CLIs with typer and rich
- Set up automated formatting and linting with ruff
- Use FastMCP for simplified MCP server implementation
- Document everything thoroughly
Contributing
- Fork the repository
- Create a feature branch:
git checkout -b feature-name
- Make your changes and add tests
- Run the test suite:
pixi run test
- Format and lint:
pixi run format && pixi run lint
- Commit your changes:
git commit -m "Add feature"
- Push to the branch:
git push origin feature-name
- Submit a pull request
License
This project is licensed under the MIT License - see the LICENSE file for details.
Acknowledgments
- Model Context Protocol for the MCP specification
- FastMCP for simplified MCP server implementation
- OpenAI Agents for agent capabilities
- pixi for modern Python package management
- Pydantic for data validation and configuration modeling
- All the amazing open-source tools that make this project possible
Francisco - Intelligent Python development assistant with self-replication capabilities ๐คโจ