Skip to main content
Glama

Insitu

Identidad situada para agentes. Quién eres aquí.

Insitu almacena stanzas reutilizables (secciones de orientación permanente) y las compone en un protocolo para el proyecto en el que estás. materialize escribe ese protocolo en archivos que el host ya inyecta al inicio de la sesión. Puedes redactar con list_stanzas y los resúmenes de tamaño. Los agentes usan resolve_protocol para inspeccionar y extraer las stanzas available.

No modela repositorios, componentes ni hechos del sistema. Eso es una herramienta de contexto de desarrollo (ContextForge, en la configuración de referencia). Se pretende que ambos funcionen lado a lado.

Estado

Diseño bloqueado el 2026-08-17 (DESIGN.md v0.5). La ruta de lectura, los roles (§6.1), validate / where_used y materialize están implementados. Las herramientas de mutación esperan hasta después del primer dogfood. Próximo paso activo: STATUS.md.

Related MCP server: Home Lab Context MCP

Instalación

Requiere Python 3.11+ y uv.

cd insitu
uv sync
uv run pytest
uv run insitu

uv run insitu inicia el servidor MCP en stdio.

Raíz del vault

Un vault por proceso, en este orden:

  1. INSITU_HOME

  2. --vault /path/to/vault

  3. ~/.insitu

Un vault nuevo es solo carpetas en disco (stanzas/, projects/, opcional config/surfaces.yaml). examples/vault/ en este repositorio es una muestra ficticia a la que puedes apuntar:

uv run insitu --vault examples/vault

No copies un vault personal en este repositorio público.

Añadir el servidor MCP a un host

Consulta install/mcp.json.examples.md para fragmentos de Cursor, Claude Code y Grok. Forma típica:

{
  "mcpServers": {
    "insitu": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/insitu", "insitu"],
      "env": { "INSITU_HOME": "/path/to/your/vault" }
    }
  }
}

Copiar los tres routers (una vez, global al usuario)

Los routers le indican al host que Insitu existe. No son el protocolo del proyecto.

Host

Copiar desde

Copiar a

Cursor

install/routers/cursor.mdc

~/.cursor/rules/insitu-router.mdc

Claude

install/routers/claude.md

~/.claude/rules/insitu-router.md

Grok

install/routers/grok.md

~/.grok/rules/insitu-router.md

Opcional: pega install/AGENTS.md en un archivo de constitución a mano. materialize nunca escribe AGENTS.md, CLAUDE.md ni CLAUDE.local.md.

Habilita los adaptadores de host en el vault con config/surfaces.yaml (grok, claude, cursor). Luego, desde un checkout del proyecto, llama a materialize. Esto escribe PROTOCOL.md y los archivos de adaptador en .grok/rules/, .claude/rules/ y .cursor/rules/.

Uso previsto

# you, after a vault or map change
materialize               # PROTOCOL.md + host adapters (.grok/.claude/.cursor rules)

# agent, live / on demand
resolve_protocol          # inspect weight, refresh, compare to the materialized header
get_stanza ...            # pull an available stanza

# you, registering a new project
list_stanzas              # what exists, and how heavy each piece is
link_stanza ...           # after the write path exists
get_project               # how heavy is this project's protocol?

Desarrollo

uv sync
uv run pytest
uv run insitu

Python 3.11+, FastMCP. Consulta AGENTS.md si eres un agente que trabaja en este repositorio.

Licencia

MIT. Consulta LICENSE.

Available Tools

44 tools
create_projectC

Create a project map and optional notes. Creating _global when missing is allowed.

Inputs: project (required), working_folder (required), aka, why, +8 more. Returns: object

create_roleB

Create a role file. The new role is on no project. Optional why is for the git message only.

Inputs: role_id (required), why, core, name, +2 more. Returns: object

create_skillA

Create skills//SKILL.md. Does not auto-link. Optional why writes provenance/skills/.md.

Inputs: content (required), skill_id (required), description (required), why. Returns: object

create_stanzaA

Create a stanza and append a why-log entry. Does not link it to a project. Subject to review policy.

Inputs: why (required), title (required), content (required), stanza_id (required), +3 more. Returns: object

delete_projectA

Delete a project directory. Preview unless confirm=true with the preview's expected. Cannot delete _global. Do not call unless the user explicitly asked to delete this project. Findings are not a reason to delete.

Inputs: project (required), working_folder (required), why, confirm, +1 more. Returns: object

delete_roleA

Delete a role. Preview unless confirm=true with the preview's expected. Do not call unless the user explicitly asked to delete this role. Findings are not a reason to delete.

Inputs: role_id (required), why, confirm, expected. Returns: object

delete_skillB

Delete a skill. Preview unless confirm=true with the preview's expected. Do not call unless the user explicitly asked to delete this skill.

Inputs: skill_id (required), why, confirm, expected. Returns: object

delete_stanzaA

Delete a stanza. Preview unless confirm=true with the preview's expected. Do not call unless the user explicitly asked to delete this stanza. Findings are not a reason to delete.

Inputs: why (required), stanza_id (required), confirm, expected. Returns: object

fetch_packC

Admin: seed library///. No map change. Confirm if refreshing changed bytes.

Inputs: pack (required), version (required), path, repo, +2 more. Returns: object

get_packC

One pack id: versions on disk, members, and which maps pin it.

Inputs: pack (required). Returns: object

get_projectA

Return a project map, notes, roles, and protocol size summary without the protocol body.

Inputs: project (required). Returns: object

get_roleA

Return one role file, member stanza metadata and sizes, and projects that include it.

Inputs: role_id (required). Returns: object

get_skillB

Return one skill: frontmatter, body, size, and payload file list. Optional project looks through that map's pack skills.

Inputs: skill_id (required), project. Returns: object

get_stanzaA

Return one stanza by id (path relative to stanzas/, no .md). Optional project looks through that map's imports.

Inputs: stanza_id (required), project. Returns: object

grantB

Admin only: set a project's operator class to admin or bound.

Inputs: project (required), operator_class (required), working_folder (required). Returns: object

install_capabilityC

This project uses the whole pack at version or latest. Pull onto the shelf if needed.

Inputs: pack (required), project (required), version (required), working_folder (required). Returns: object

install_skillC

This project uses one skill from a pack version. Pull onto the shelf if needed. Does not copy into native skills/.

Inputs: project (required), version (required), skill_id (required), working_folder (required), +1 more. Returns: object

install_stanzaC

This project uses one stanza from a pack version. Pull onto the shelf if needed. target is core or on_demand.

Inputs: project (required), version (required), stanza_id (required), working_folder (required), +2 more. Returns: object

list_on_demandA

List on-demand stanzas associated with a project (id, title, description, size).

Inputs: project (required). Returns: object

list_packsA

Shelf inventory: pack ids, versions, which maps use which, unreferenced versions.

Inputs: no named parameters. Returns: object

list_projectsA

List projects including _global, labels, and composed-protocol size summaries.

Inputs: no named parameters. Returns: object

list_rolesA

List role packs with id, name, description, member counts, and composed core size.

Inputs: no named parameters. Returns: object

list_skillsB

List vault skills with name, description, size, and which projects list them. Not session start.

Inputs: prefix. Returns: object

list_stanzasA

List stanzas with title, description, tags, roles, and size. Optional prefix, tag, or role filter.

Inputs: tag, role, prefix. Returns: object

materializeC

Write PROTOCOL.md and configured host adapters into the working folder.

Inputs: working_folder (required), project. Returns: object

operatorsA

Inspect: operator classes, the registered admins, and the default class.

Inputs: no named parameters. Returns: object

project_statusB

Folder inspect card: map, sourced core ids, size, on-demand ids, disk freshness. No stanza bodies. Inspect only.

Inputs: working_folder (required), project. Returns: object

remove_packA

Admin: preview then confirm. Remove a shelf version (or all versions of an id).

Inputs: pack (required), confirm, version, expected. Returns: object

resolve_protocolC

Return the composed protocol for a project: core bodies, on-demand index, size.

Inputs: project (required). Returns: object

revokeA

Admin only: drop a project back to the default class. Cannot revoke the last admin.

Inputs: project (required), working_folder (required). Returns: object

uninstall_capabilityC

Drop this map's whole-capability record. Shelf unchanged.

Inputs: pack (required), project (required), version (required), working_folder (required). Returns: object

uninstall_skillB

Drop this pack skill from this map's import record. Shelf unchanged.

Inputs: pack (required), project (required), version (required), skill_id (required), +1 more. Returns: object

uninstall_stanzaB

Drop this stanza from this map's import record. Shelf unchanged.

Inputs: pack (required), project (required), version (required), stanza_id (required), +1 more. Returns: object

update_projectB

Incrementally update a project map. Attach/detach role writes immediately and reports members, weight, and affects_projects.

Inputs: project (required), working_folder (required), aka, why, +12 more. Returns: object

update_roleA

Update a role. Name/description write now. Member add/remove is preview unless confirm=true with the preview's expected.

Inputs: role_id (required), why, name, confirm, +6 more. Returns: object

update_skillC

Update SKILL.md frontmatter and/or body. Surfaces where_used and affects_projects.

Inputs: skill_id (required), why, content, description. Returns: object

update_stanzaA

Update a stanza, append a why-log entry, and return where_used. Subject to review policy.

Inputs: why (required), stanza_id (required), tags, roles, +3 more. Returns: object

validateA

Vault health check. Read-only unless fix=true. Issues fail ok; findings do not. Fixes follow the review dial and never consume findings.

Inputs: fix. Returns: object

where_usedA

List every project map and role file that references a stanza.

Inputs: stanza_id (required). Returns: object

where_used_skillB

List project maps that include this skill. Roles never appear.

Inputs: skill_id (required). Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.9/5.0

    Scored across 44 tools

    Disambiguation3/5

    The resource-action pattern makes most tools clearly distinct, but several near-duplicate pairs exist: where_used vs where_used_skill, link_stanza vs install_stanza, link_skill vs install_skill, and get_project vs project_status. The descriptions draw clear lines (native vs pack, stanza vs skill), but an agent must read carefully to avoid misselection.

    Naming Consistency4/5

    The core CRUD naming (list/get/create/update/delete + resource) is highly consistent across projects, stanzas, roles, and skills, and the pack install/uninstall family follows a clear pattern. Deviations like grant, revoke, operators, validate, materialize, and the noun-verb project_status break the convention, and where_used_skill is suffixed inconsistently relative to the generic where_used.

    Tool Count2/5

    At 44 tools, this server is well into the 'too many' range per the calibration, even though each tool appears justified by the breadth of the domain. An agent must navigate a large surface spanning projects, stanzas, roles, skills, packs, admin, and utilities.

    Completeness4/5

    Every core resource has full lifecycle coverage — create/get/list/update/delete for projects, stanzas, roles, and skills — plus linking and pack import/export for external content. Minor gaps (no why-log read tool, no findings or review-policy management surface) prevent a 5, but core workflows have no dead ends.

    Related MCP Connectors

    Related MCP Servers