higpertext-mcp
Summary: The server lets you initialize/update higpertext project configuration, sync the active profile to assistant-native files, and expose installed higpertext-cli capabilities as MCP tools.
higpertext-configure-project: creates the minimal.higpertext/config/environment.json,mcp_external.json, and.mcp.jsonfor a registered profile without overwriting existing setup.higpertext-generate-codex-rules: generates/updates the active profile's rules section inAGENTS.mdfor Codex.higpertext-render-adapters: generates native files for Codex, Claude, Gemini, Copilot, Antigravity, and OpenCode from the active profile; an emptyassistantslist renders all adapters.Per the README, the server also dynamically registers installed
higpertext-clicapabilities (e.g.common.grep-search,git.diff,common.smart-read) as validated MCP tools, returning structuredok,summary,data,artifacts,warnings, anderror.
Provides tools for working with Git repositories, including viewing diffs, listing tracked files, and creating commits.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@higpertext-mcp run a secret scan on the current project and summarize findings"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
higpertext-mcp
Eventos canónicos
Los adapters traducen los eventos nativos de cada asistente a un catálogo
independiente de plataforma: SESSION_STARTED, PROMPT_RECEIVED,
PLAN_CREATED, ACTION_REQUESTED, ACTION_AUTHORIZED, ACTION_STARTED,
ACTION_COMPLETED, ACTION_FAILED, CONTEXT_COMPACTING y
SESSION_FINISHED.
La traducción se implementa en higpertext_mcp.events y
higpertext_mcp.hook_protocol. Cada adapter declara qué eventos puede
observar y sus limitaciones. En particular, ACTION_AUTHORIZED no lo emite
un hook: la autorización efectiva pertenece al gateway/controller.
Related MCP server: mcp_server_for_claudes_toolbox
Catálogo central de adaptadores
La matriz de compatibilidad vive en
src/higpertext_mcp/adapter_catalog.py. Es la única fuente de verdad para los
destinos nativos, eventos, aliases de tools, skills y agents, y el
estado de cada integración. Los renderizadores consultan ese catálogo y no
deben declarar asistentes o rutas por separado.
Un adaptador puede ser native (formato documentado), bridge (puente local)
o no tener una feature concreta. Que exista un hook no convierte el evento en
una garantía de seguridad: la autorización efectiva sigue perteneciendo al
gateway/controller.
Servidor MCP que expone capabilities de higpertext-cli como tools reales
(function-calling), en vez del interceptor de texto sobre Bash que usaba antes el motor.
Documentación completa: docs/installation.md (instalación,
.mcp.json, cómo probarlo desde Postman) y docs/api/README.md (contrato de respuesta y catálogo de tools con ejemplos dearguments).
Por qué existe
Ver la discusión de diseño en el historial del proyecto higpertext-cli
(bash_rules.py, hook_bash_guard.py): los redirects de texto sobre Bash
(grep, git diff/status, etc.) interceptaban el comando, ejecutaban la capability
en un subprocess aparte y el comando original corría de todos modos — ruido sin
efecto real. Este servidor reemplaza esa capa con tools MCP genuinas: el modelo
invoca la capability directamente, con schema validado, sin pasar por Bash.
Contrato de resultados
Cada invocación devuelve structuredContent, no una transcripción de terminal:
{
"ok": true,
"summary": "Resultado breve para el agente",
"data": {},
"artifacts": [],
"warnings": [],
"error": null
}Las capabilities que todavía escriben texto se encapsulan temporalmente en
data.text; el mensaje visible del tool contiene sólo summary. El CLI htx
sigue disponible para personas y CI, pero ya no imprime el stdout completo de
una capability exitosa.
Qué capabilities se exponen
No es un set fijo: se registra como tool cualquier capability que (a) el
motor higpertext-cli instalado traiga y (b) esté listada en capabilities
del perfil activo del proyecto destino (.higpertext/config/environment.json
→ active_profile → src/config/profiles/<perfil>.json). Sin perfil activo o
legible, no se expone ninguna tool (fail-closed).
El catálogo probado hasta ahora (9 capabilities reales, documentadas con
ejemplos en docs/api/tools.md):
common.grep-search, git.diff, git.ls-files, common.smart-read,
common.code-skeletonizer, common.memory-manager, git.committer,
security.secret-scanner, common.quality-resolver. Un décimo id,
common.knowledge-asker, sigue en annotations.py pero no tiene definición
JSON en el motor instalado — nunca se expone hasta que exista.
Instalación
higpertext-cli es un paquete propietario, no está en PyPI — se instala editable
apuntando al checkout local, igual que agent-bootstrap lo hace para agentes
externos:
python3 -m venv .venv
.venv/bin/pip install -e /ruta/a/higpertext-cli
.venv/bin/pip install -e .Uso con Claude Code
Agregar en .mcp.json del proyecto destino (el que tiene su propio
.higpertext/):
{
"mcpServers": {
"higpertext": {
"command": "/ruta/a/higpertext-mcp/.venv/bin/python",
"args": ["-m", "higpertext_mcp.server"]
}
}
}El servidor no usa la raíz del motor ni el cwd como selección implícita. En
stdio se debe configurar HIGPERTEXT_PROJECT_ROOT; en HTTP cada operación debe
enviar project_id o root_path, que se valida contra el registro de proyectos.
Para limitar adicionalmente el filesystem de una instancia HTTP/Docker, el
operador puede definir HIGPERTEXT_ALLOWED_PROJECT_ROOTS con rutas host
canónicas separadas por : (o por os.pathsep en la plataforma).
Limitación conocida (v1): la lista de tools se arma una sola vez, al conectar.
Si cambiás de perfil (htx profile load) a mitad de sesión, hay que reconectar el
server para que la lista de tools se actualice — no hay refresh automático todavía.
Tests
.venv/bin/python -m pytest tests -qDos tests (test_load_tool_spec_real_grep_search,
test_call_capability_real_grep_search_on_this_repo) son de integración real: usan
la definición real de common.grep-search del motor instalado, así que hay que
correrlos con higpertext-cli instalado editable (ver Instalación) y cwd dentro de
un checkout de higpertext-cli real.
Roadmap (no construido todavía)
Resto de las ~37 capabilities restantes del motor.
Refresh de tools al cambiar de perfil sin reconectar.
Confirmación explícita antes de invocar capabilities con side-effects destructivos (
git.committer,common.memory-manager).
Available Tools
3 toolshigpertext-configure-projectAIdempotent
Crea la configuración mínima de higpertext en el proyecto actual: .higpertext/config/environment.json, mcp_external.json y .mcp.json. No sobrescribe una configuración existente.
Inputs: profile (required).
higpertext-generate-codex-rulesAIdempotent
Genera o actualiza la sección de reglas del perfil activo en AGENTS.md para Codex.
Inputs: no named parameters.
higpertext-render-adaptersAIdempotent
Genera los archivos nativos de Codex, Claude, Gemini, Copilot, Antigravity y OpenCode desde el perfil activo.
Inputs: assistants.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool targets a distinct stage: project setup, Codex-specific rules generation, and multi-adapter rendering. There is slight potential confusion between generate-codex-rules and render-adapters since both involve producing Codex-related outputs, but their specific outputs and purposes are clearly separated.
All tool names follow the consistent pattern `higpertext-<verb>-<object>`, using lowercase with hyphens throughout. The verbs 'configure', 'generate', and 'render' clearly indicate different actions while maintaining a uniform grammatical structure.
With only three tools, the set is compact and well-scoped to the server's apparent purpose: setting up and generating higpertext configuration outputs. Each tool addresses a necessary step in the workflow without unnecessary redundancy or bloat.
The three tools cover the main lifecycle: initialize project config, generate Codex rules, and render adapters for multiple assistants. Minor gaps exist, such as lacking a tool to inspect or validate current profiles or configurations, but agents can work around these by reading the generated files directly.
Related MCP Connectors
Find, vet, and run MCP tools through a secure audited gateway with prompt-injection risk scoring
Zero-setup MCP gateway securely connecting AI to your tools with authentication and workflows
Build, validate, deploy — HTTP APIs, cron jobs, webhooks and MCP tools — from your AI client.
The OpenRouter for tools. One MCP connection gives any AI agent 254 hosted tools, pay per call.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceDynamically exposes CLI/bash commands as MCP tools and creates structured AI prompt templates through simple YAML configuration files, enabling users to transform any command-line tool into an MCP-compatible interface without writing code.20Apache 2.0
- FlicenseNot gradedqualityDmaintenanceExposes a set of CLI tools (test generation, documentation generation, linting, test running, code search) to AI assistants via MCP, allowing them to perform these tasks through natural language.3-
- FlicenseNot gradedqualityBmaintenanceEnables MCP-compatible AI clients to invoke CLI-driven agent tools over Streamable HTTP, including shell execution, file operations, patching, image viewing, web search, and nested agent tasks, with permission modes and real-time progress streaming.-
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to discover, retrieve, and invoke 80+ SkillHub practical skills as standardized MCP tools over stdio, covering coding, office, content creation, data analysis, and security operations.MIT No Attribution