project-mcp-tools
project-mcp-tools
Un framework en Python que expone herramientas de desarrollo a través de tres protocolos simultáneamente: MCP (Model Context Protocol), API REST y CLI, todo ello desde un único registro de herramientas compartido.
Descripción general
project-mcp-tools resuelve el problema de mantener backends de herramientas separados para distintos consumidores. Escribe una herramienta una sola vez usando el decorador @tool(), y estará disponible al instante para:
Asistentes de IA mediante el protocolo MCP (impulsado por FastMCP)
Clientes HTTP mediante una API REST (impulsada por FastAPI + uvicorn)
Usuarios de terminal mediante una CLI (impulsada por argparse)
Las herramientas incluidas cubren el desarrollo en C++ (compilación, análisis estático, formateo, generación de clases/pruebas, análisis de árbol de includes), verificación de formato Python y operaciones git, todo ello con aislamiento de procesos mediante ejecución en subprocesos.
Instalación
Requisitos: Python 3.14+, gestor de paquetes uv
# Clone the repository
git clone <repository-url>
cd project-mcp-tools
# Install dependencies
uv syncUso
Servidor MCP
Inicia un servidor FastMCP al que los asistentes de IA pueden conectarse:
uv run mcp-serverConfigura tu cliente MCP para usar este servidor. Por ejemplo, en opencode.json en la raíz del proyecto anfitrión (el proyecto sobre el que quieres que operen las herramientas, no el directorio project-mcp-tools en sí):
{
"mcp": {
"project-mcp-tools": {
"type": "local",
"command": ["uv", "--directory", "project-mcp-tools", "run", "mcp-server", "--target-project", "../my-host-project"]
}
}
}Importante:
--directoryle indica auvdónde encontrar el paqueteproject-mcp-tools(pyproject.toml, dependencias, venv).--target-projectestablece el directorio de trabajo para el proceso MCP y todos sus subprocesos — este es el proyecto sobre el que operarán realmente las herramientas. La ruta se resuelve de forma relativa aproject-mcp-tools/(ya queuv --directorycambia el directorio de trabajo). Sin esta separación, las herramientas de git/cpp/python operarían dentro deproject-mcp-tools/en lugar de tu proyecto anfitrión.
Servidor de API REST
Inicia un servidor FastAPI en http://0.0.0.0:8000:
uv run api --target-project ../my-host-projectCada herramienta se expone como POST /tools/<tool_name>. Los parámetros de consulta de la firma de la función de la herramienta se convierten en campos del cuerpo JSON de la solicitud.
Ejemplo de solicitud:
curl -X POST http://localhost:8000/tools/git_quick_upload \
-H "Content-Type: application/json" \
-d '{"message": "my commit"}'La interfaz Swagger está disponible en http://localhost:8000/docs.
CLI
Invoca cualquier herramienta desde la terminal:
uv run cli --target-project ../my-host-project git_quick_upload --message "your commit message"--target-project debe ir antes del nombre de la herramienta. Las herramientas que no hacen referencia al proyecto anfitrión (p. ej., get_random_number) se pueden llamar sin --target-project.
Catálogo de herramientas
General
Herramienta | Firma | Descripción |
|
| Genera una imagen usando Gemini (modelo |
|
| Interpreta una imagen del proyecto anfitrión usando la visión de Gemini (modelo fijo |
|
| Devuelve información de depuración del entorno (cwd, rutas, variables de entorno) |
|
| Devuelve un número aleatorio entre |
Git
Herramienta | Firma | Descripción |
|
| Descarta todos los cambios sin confirmar y elimina los archivos no rastreados. Revierte a HEAD |
|
| Actualiza cada submódulo hasta la última confirmación remota (requiere submódulos limpios); el cambio queda sin confirmar |
|
| Ejecuta |
Python
Herramienta | Firma | Descripción |
|
| Aplica |
|
| Elimina todos los directorios |
|
| Verifica las reglas de formato de Python para los archivos especificados |
C++
Herramienta | Firma | Descripción |
|
| Aplica correcciones de formato en todos los archivos |
|
| Verifica las reglas de formato C++ para los archivos especificados |
|
| Compila todo el proyecto C++ usando Clang |
|
| Genera un nuevo archivo de clase C++ (cabecera y fuente) siguiendo la estructura del proyecto |
|
| Genera un archivo de prueba C++ para una clase existente |
|
| Analiza la jerarquía de inclusiones de un archivo C++ |
|
| Genera |
Python
Herramienta | Firma | Descripción |
|
| Aplica |
|
| Elimina todos los directorios |
|
| Verifica las reglas de formato Python para los archivos especificados |
C++
Herramienta | Firma | Descripción |
|
| Aplica correcciones de formato a todos los archivos |
|
| Verifica las reglas de formato C++ para los archivos especificados |
|
| Compila todo el proyecto C++ en paralelo |
|
| Genera una nueva clase C++ a partir de una jerarquía (p. ej., |
|
| Genera un archivo de prueba C++ |
|
| Muestra el árbol recursivo de dependencias de inclusión de un archivo C++. Por defecto usa el archivo principal del proyecto |
|
| Genera |
Python
Herramienta | Firma | Descripción |
|
| Aplica |
|
| Elimina todos los directorios |
|
| Verifica las reglas de formato Python para los archivos especificados |
C++
Herramienta | Firma | Descripción |
|
| Aplica |
|
| Compila el código C++ del proyecto anfitrión usando Clang con el estándar C++17 y advertencias estrictas |
|
| Genera un nuevo archivo de clase C++ (con |
|
| Genera un archivo de prueba C++ para una clase dada en |
|
| Genera |
|
| Muestra el árbol de inclusión recursivo de un archivo C++ (con límite de profundidad) |
Sesión
Herramienta | Firma | Descripción |
|
| Informa cuánto contexto de la ventana del modelo está usando la sesión de chat abierta actual ( |
Estructura del Proyecto
project-mcp-tools/
├── main.py # Entry point — builds tool_manager, starts servers
├── pyproject.toml # Project config, dependencies, entry points
├── tools/ # Core engine package
│ ├── __init__.py
│ ├── tool_manager.py # Core orchestrator — shared registry, tool folder loading, subprocess dispatch, CLI/API/MCP exposure
│ ├── tool.py # @tool() decorator, ToolInfo/ParameterInfo models, response contract helpers
│ ├── path_manager.py # Project/target root resolution — injectable, no global state
│ └── folder_scanner.py # Auto-discovers @tool-decorated functions in directories
├── general/ # General-purpose tools (no host project dependency)
│ ├── create_image.py # Gemini image generation tool
│ ├── describe_image.py # Gemini image interpretation tool
│ ├── debug.py # Environment debugging tool
│ └── get_random_number.py # Random number generator
├── sak/
│ ├── common.py # Utilities (process creation, JSON, assertions)
│ └── fso/ # File system objects
├── lib/
│ ├── base_verifier.py # Abstract regex-based code formatter
│ ├── project_config.py # Global project configuration
│ ├── project_file.py # Abstract source file with license header management
│ └── template.py # Jinja-like template engine with imports and lists
├── cpp/
│ ├── analyze.py # C++ full analysis tool
│ ├── code_verifier.py # C++ formatting verification tool
│ ├── compile.py # C++ parallel compilation tool
│ ├── create_class.py # C++ class scaffolding tool
│ ├── create_test.py # C++ test scaffolding tool
│ ├── include_tree.py # C++ include dependency tree tool
│ └── cpp_lib/ # C++ domain library (compiler, model, verifier, build)
├── python/
│ ├── analyze.py # Python full analysis tool
│ ├── code_verifier.py # Python formatting verification tool
│ └── python_lib/ # Python domain library (model, verifier, config)
├── session/
│ ├── context_usage.py # opencode session context usage tool
│ └── session_lib/ # Session domain library (opencode database reader)
├── git/
│ ├── discard_changes.py # Git reset + clean tool
│ └── quick_upload.py # Git pull/add/commit/push tool
├── resources/
│ └── images/ # Generated images (from create_image tool)
├── .agents/
│ └── skills/ # AI assistant skills (compliance audit, uv package manager)
└── docs/
├── templates/ # Template files for class/test scaffolding (user zone)
├── example/ # Usage examples (e.g. google-genai.py) (user zone)
└── agent/ # AI-managed knowledge base (architecture, guides, workflows, status)
├── architecture.md # System architecture and design decisions
├── development/ # Tool development guide
├── style-guide/ # Coding style guides
├── workflow/ # Workflow documentation
└── status.md # Agent task statusArquitectura
El sistema está construido en torno a un objeto central tool_manager que mantiene el registro compartido de herramientas y gestiona los tres transportes (CLI, API REST y MCP).
Para un desglose detallado de la arquitectura del sistema, decisiones de diseño y el mecanismo del proyecto objetivo, consulta la guía System Architecture.
Añadir una Nueva Herramienta
Para añadir una nueva herramienta, crea un archivo Python en una carpeta de herramientas existente (o una nueva) y decora tu función con @tool().
Para un tutorial paso a paso y pautas sobre cómo estructurar la capa de herramientas y las bibliotecas de dominio, consulta la Guía de Desarrollo de Herramientas.
Configuración
La configuración global y específica de cada dominio está centralizada en el código. Para ver la lista completa de claves y valores de configuración, consulta System Architecture - Configuración centralizada.
Convenciones de Codificación
Todo el código de este proyecto debe cumplir con pautas estrictas, incluido el uso exclusivo de snake_case para todos los identificadores y reglas de espaciado específicas. Para la lista completa de pautas, consulta la Guía de Estilo Python.
Licencia
GNU General Public License v3.0 — consulta los encabezados de licencia en los archivos fuente para más detalles.
This server cannot be installed
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
Package intelligence MCP for AI agents — 22 tools, 19 ecosystems, AGPL SDK, free.
Free public MCP for AI agents — 193 tools, 44 workflows. No API key.
AI Reasoning Cache & Consensus Layer with 11 MCP tools via Streamable HTTP.
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/maxwellaguiarsilva/project-mcp-tools'
If you have feedback or need assistance with the MCP directory API, please join our Discord server