Skip to main content
Glama

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 sync

Uso

Servidor MCP

Inicia un servidor FastMCP al que los asistentes de IA pueden conectarse:

uv run mcp-server

Configura 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: --directory le indica a uv dónde encontrar el paquete project-mcp-tools (pyproject.toml, dependencias, venv). --target-project establece 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 a project-mcp-tools/ (ya que uv --directory cambia el directorio de trabajo). Sin esta separación, las herramientas de git/cpp/python operarían dentro de project-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-project

Cada 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

create_image

(description: str, file_name: str | None = None) -> str

Genera una imagen usando Gemini (modelo gemini-3.1-flash-lite-image) a partir de la descripción de texto dada. La guarda en resources/images/

describe_image

(image_path: str, description: str) -> str

Interpreta una imagen del proyecto anfitrión usando la visión de Gemini (modelo fijo gemini-flash-lite-latest) para modelos sin capacidad de visión. image_path es relativo al proyecto anfitrión

debug

() -> str

Devuelve información de depuración del entorno (cwd, rutas, variables de entorno)

get_random_number

(start: int = 1, end: int = 100) -> str

Devuelve un número aleatorio entre start y end

Git

Herramienta

Firma

Descripción

git_discard_changes

() -> str

Descarta todos los cambios sin confirmar y elimina los archivos no rastreados. Revierte a HEAD

git_pull_submodules

() -> str

Actualiza cada submódulo hasta la última confirmación remota (requiere submódulos limpios); el cambio queda sin confirmar

git_quick_upload

(message: str) -> str

Ejecuta git pull, git add ., git commit -m <mensaje> y git push

Python

Herramienta

Firma

Descripción

python_analyze

() -> str

Aplica python_code_verifier a todos los archivos *.py del directorio de herramientas

python_clear

() -> str

Elimina todos los directorios __pycache__ bajo el directorio actual

python_code_verifier

(files: list[str]) -> str

Verifica las reglas de formato de Python para los archivos especificados

C++

Herramienta

Firma

Descripción

cpp_analyze

() -> str

Aplica correcciones de formato en todos los archivos *.hpp/*.cpp y luego ejecuta el análisis estático

cpp_code_verifier

(files: list[str]) -> str

Verifica las reglas de formato C++ para los archivos especificados

cpp_compile

() -> str

Compila todo el proyecto C++ usando Clang

cpp_create_class

(class_hierarchy: str, include_list: list[str] = []) -> str

Genera un nuevo archivo de clase C++ (cabecera y fuente) siguiendo la estructura del proyecto

cpp_create_test

(class_hierarchy: str, test_name: str | None = None) -> str

Genera un archivo de prueba C++ para una clase existente

cpp_analyze_include_tree

(file_path: str) -> str

Analiza la jerarquía de inclusiones de un archivo C++

cpp_generate_opengl

() -> str

Genera opengl.htm con referencias de OpenGL 4.6 en el directorio raíz del proyecto anfitrión

Python

Herramienta

Firma

Descripción

python_analyze

() -> str

Aplica python_code_verifier a todos los archivos *.py en el directorio de herramientas

python_clear

() -> str

Elimina todos los directorios __pycache__ bajo el directorio actual

python_code_verifier

(files: list[str]) -> str

Verifica las reglas de formato Python para los archivos especificados

C++

Herramienta

Firma

Descripción

cpp_analyze

() -> str

Aplica correcciones de formato a todos los archivos .cpp/.hpp y luego ejecuta el análisis estático con Clang

cpp_code_verifier

(files: list[str]) -> str

Verifica las reglas de formato C++ para los archivos especificados

cpp_compile

() -> str

Compila todo el proyecto C++ en paralelo

cpp_create_class

(class_hierarchy: str, include_list: list[str] = [], create_header_only: bool = False) -> str

Genera una nueva clase C++ a partir de una jerarquía (p. ej., "game/player")

cpp_create_test

(hierarchy: str, flg_adhoc: bool = False, include_list: list[str] = []) -> str

Genera un archivo de prueba C++

cpp_analyze_includes

(file_path: str = None) -> str

Muestra el árbol recursivo de dependencias de inclusión de un archivo C++. Por defecto usa el archivo principal del proyecto

cpp_generate_opengl_html

() -> str

Genera opengl.htm, un archivo HTML único con el perfil central de OpenGL 4.6. Lee include/glad/snake_case.hpp del proyecto anfitrión y escribe las refpages oficiales de Khronos en /tmp y el HTML resultante en la raíz del proyecto anfitrión

Python

Herramienta

Firma

Descripción

python_analyze

() -> str

Aplica python_code_verifier sobre todos los archivos .py del directorio de herramientas

python_clear

() -> str

Elimina todos los directorios __pycache__ bajo el directorio actual

python_code_verifier

(files: list[str]) -> str

Verifica las reglas de formato Python para los archivos especificados

C++

Herramienta

Firma

Descripción

cpp_analyze

() -> str

Aplica cpp_code_verifier a todos los archivos *.cpp y *.hpp del proyecto anfitrión, luego ejecuta un análisis estático con clang-tidy

cpp_compile

() -> str

Compila el código C++ del proyecto anfitrión usando Clang con el estándar C++17 y advertencias estrictas

cpp_create_class

(class_name: str, output_dir: str | None = None) -> str

Genera un nuevo archivo de clase C++ (con #pragma once, documentación y ajuste inline) en include/ o en el directorio especificado

cpp_create_test

(class_name: str, test_name: str | None = None) -> str

Genera un archivo de prueba C++ para una clase dada en tests/

cpp_generate_opengl

() -> str

Genera opengl.h/opengl.cpp a partir de la especificación de OpenGL (usando glad) y actualiza los includes

cpp_analyze_include_tree

(file_path: str, max_depth: int = 0) -> str

Muestra el árbol de inclusión recursivo de un archivo C++ (con límite de profundidad)

Sesión

Herramienta

Firma

Descripción

session_context_usage

(session_id: str | None = None, context_limit: int | None = None) -> str

Informa cuánto contexto de la ventana del modelo está usando la sesión de chat abierta actual (context_used, context_percent, límite de contexto). Lee directamente la base de datos de opencode; auto-detecta la sesión activa en el proyecto objetivo. Consulta conocimiento de opencode

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 status

Arquitectura

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.

-
license - not tested
-
quality - not tested
C
maintenance

Maintenance

Maintainers
Response time
Release cycle
Releases (12mo)
Commit activity

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.

View all MCP Connectors

Latest Blog Posts

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