Exposes higpertext-cli capabilities as MCP tools and lets you configure/render higpertext project setup.
Invoke real capabilities directly with validated schema: 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 (only those installed and listed in the active profile).
Create minimal .higpertext configuration (environment.json, mcp_external.json, .mcp.json) with higpertext-configure-project; idempotent and does not overwrite existing config.
Generate or update the AGENTS.md rules section for the active profile via higpertext-generate-codex-rules.
Render native adapter files for Codex, Claude, Gemini, Copilot, Antigravity, and OpenCode via higpertext-render-adapters.
Return structured results (ok, summary, data, artifacts, warnings, error) instead of raw terminal output.
Fail closed when no active profile is readable; tool list is fixed at connection time until reconfigured.
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.
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.
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).
Related MCP server: mcp_server_for_claudes_toolbox
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.
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.
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.
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 .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 resuelve la raíz del proyecto por cwd del proceso (el cliente MCP
local lo lanza con cwd = raíz del proyecto). Para forzar otra raíz, setear
HIGPERTEXT_PROJECT_ROOT en el bloque env de la entrada del server en
.mcp.json.
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.
.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.
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).
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.
| Name | Required | Description | Default |
|---|---|---|---|
| profile | Yes | Nombre de un perfil ya registrado en higpertext-server-profile. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag idempotentHint=true and destructiveHint=false, and the description adds concrete behavioral context by stating it does not overwrite an existing configuration. It also clarifies that the tool writes new files, consistent with readOnlyHint=false.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence front-loads the primary action, lists the exact files created, and includes the critical non-overwrite guarantee. There is no filler or redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one well-documented parameter, safety-related annotations, and no output schema, the description is complete enough to support correct invocation. It states what is created, where, and the key side-effect constraint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the profile parameter already carries a meaningful description ('Nombre de un perfil ya registrado...'). The tool description adds no parameter-specific information, but the schema fully covers this simple single-parameter case.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Crea') and names the exact resource: the minimal higpertext configuration in the current project, including the specific files to be created. The listed artifacts clearly distinguish it from the sibling tools, which generate codex rules or render adapters.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies use at project setup by stating it creates the minimal configuration in the current project. It does not explicitly mention alternatives or exclusions, but the context is unambiguous enough for an agent to know when to invoke it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Genera o actualiza la sección de reglas del perfil activo en AGENTS.md para Codex.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey idempotence and non-destructiveness, so the description does not need to restate those. It adds useful context by identifying the target file and scope, though it does not mention details like whether AGENTS.md will be created if missing or whether existing rule content is fully replaced. This is acceptable given the annotation coverage, so the score stays at baseline.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that front-loads the action and specifies the exact target resource. There is no filler or redundant wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, parameterless, idempotent tool, the description covers the core action, the target file, and the scope. However, it lacks any usage routing or note about prerequisites like having an active profile, which keeps it just short of fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema is empty, so there is no parameter semantics burden on the description. The baseline for zero-parameter tools is 4, and the description provides no irrelevant parameter information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('genera o actualiza') and resource ('sección de reglas del perfil activo en AGENTS.md para Codex'). This clearly distinguishes it from the sibling tools, which concern project configuration and adapter rendering, not Codex rules generation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus its siblings, nor any exclusions or prerequisites. Usage is only implied by the tool name and description, not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Genera los archivos nativos de Codex, Claude, Gemini, Copilot, Antigravity y OpenCode desde el perfil activo.
| Name | Required | Description | Default |
|---|---|---|---|
| assistants | No | Adapters a renderizar; vacío significa todos. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare that the tool is non-read-only, idempotent, and non-destructive. The description adds that it generates native files from the active profile, but it does not disclose where files are written or whether existing generated files are replaced. It does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence with the core action front-loaded. The list of assistants is necessary and not padded, making it both concise and well structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity tool with one optional parameter, the description, schema, and annotations jointly cover what is generated, from where, and the safety profile. It could be more explicit about prerequisites or the exact output/return behavior, but nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully documents the single parameter 'assistants', including its enum values and the meaning of an empty array. The description enumerates the same assistant names but adds no additional semantic detail beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific action ('Genera') and a precise resource ('los archivos nativos de Codex, Claude, Gemini, Copilot, Antigravity y OpenCode'), while also specifying the source ('desde el perfil activo'). This clearly distinguishes it from siblings like higpertext-generate-codex-rules, which is narrower in scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'desde el perfil activo' implies the intended context: generate adapter files from the currently active profile. However, the description does not explicitly say when to prefer this tool over its siblings or when not to use it, leaving alternative routing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0higpertext-configure-projecthigpertext-generate-codex-ruleshigpertext-render-adaptersScored 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.
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.