MCP 服务器

MCP Framework Personal

A production-grade MCP server framework providing multiple specialized servers for tabular data, documents, calendars, markdown, prompt engineering, and general utilities.

README

🧠 MCP Framework Personal

Framework de servidores MCP (Model Context Protocol) production-grade para uso local y producción.

Servidores incluidos

Servidor	Descripción	Tools
`mcp-tabular`	Excel, CSV, ODS, TSV → JSON estándar	8 tools
`mcp-documents`	PDF, Word, PPT, ODT, OCR	12 tools
`mcp-calendar`	Días hábiles México + Divisas	14 tools
`mcp-markdown`	Leer, analizar, transformar .md	12 tools
`mcp-prompt-engineer`	Analizar y mejorar prompts LLM	10 tools
`mcp-utils`	Utilidades generales (hash, regex, JSON...)	18 tools

Stack Técnico

SDK: mcp[cli] oficial (Anthropic) + FastMCP 2.x
Package manager: uv (workspaces)
Tipado: Pydantic v2 + type hints completos
Logging: structlog (JSON en prod, colorido en dev)
Config: pydantic-settings (12-Factor App)
Testing: pytest + pytest-asyncio
Linting: ruff + mypy
Docker: Multi-stage builds, non-root, healthchecks

Requisitos

Python 3.11+
uv instalado
Docker Desktop (para modo producción)
Tesseract OCR (para OCR en mcp-documents)

Instalar uv (si no lo tienes)

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Instalar Tesseract OCR (Windows)

Descargar desde: https://github.com/UB-Mannheim/tesseract/wiki

Instalador: tesseract-ocr-w64-setup-5.x.x.exe
Agregar al PATH: C:\Program Files\Tesseract-OCR\

Inicio Rápido

1. Instalar dependencias

cd c:/Users/germa/Documents/IA/mcps
uv sync --all-packages

2. Configurar variables de entorno

cp .env.example .env
# Editar .env si necesitas API keys

3. Usar con Claude Desktop

Copia el contenido de claude_desktop_config.json a tu configuración de Claude Desktop:

Windows: %APPDATA%\Claude\claude_desktop_config.json

Reinicia Claude Desktop. Los MCPs aparecerán automáticamente.

4. Probar un servidor (modo desarrollo)

# Iniciar servidor con hot-reload
make dev-mcp-tabular

# O usar MCP Inspector (interfaz visual)
make inspect SERVER=mcp-tabular

Comandos Makefile

make help              # Ver todos los comandos
make install           # Instalar todas las dependencias
make install-dev       # Instalar con dev tools + pre-commit
make dev-mcp-tabular   # Iniciar servidor específico en dev
make test              # Ejecutar todos los tests
make lint              # Ruff + mypy
make format            # Formatear código
make build             # Build Docker images
make up                # Levantar en Docker
make down              # Parar Docker
make logs              # Ver logs
make status            # Verificar herramientas instaladas

Estructura del Proyecto

mcps/
├── shared/                    # Librería compartida (modelos, logging, config)
├── mcp-tabular/               # Servidor archivos tabulares
├── mcp-documents/             # Servidor documentos ricos
├── mcp-calendar/              # Servidor calendario + divisas
├── mcp-markdown/              # Servidor markdown
├── mcp-prompt-engineer/       # Servidor ingeniería de prompts
├── mcp-utils/                 # Servidor utilidades
├── docker-compose.yml         # Orquestación
├── pyproject.toml             # Workspace root
├── Makefile                   # CLI operacional
├── claude_desktop_config.json # Config Claude Desktop
└── .env.example               # Variables de entorno

Despliegue en Producción (Docker)

# Copiar y configurar .env
cp .env.example .env
nano .env

# Build y levantar
make build
make up

# Verificar estado
make ps
make logs

Configuración para Claude Desktop (producción Docker)

Si usas Docker en producción, actualiza claude_desktop_config.json para usar los contenedores:

{
  "mcpServers": {
    "mcp-tabular": {
      "command": "docker",
      "args": ["run", "--rm", "-i",
               "-v", "C:/ruta/a/datos:/data:ro",
               "mcp-tabular:latest"]
    }
  }
}