Skip to main content
Glama

Insitu

面向智能体的情境化身份。你在这里是谁。

Insitu 存储可复用的 段落(即常驻指导的章节),并将它们组合成你当前所在项目的协议。materialize 将该协议写入宿主在会话启动时已经注入的文件中。你通过 list_stanzas 和大小摘要进行编写。智能体使用 resolve_protocol 来检查并拉取 available 段落。

它不模拟仓库、组件或系统事实。那是开发上下文工具(参考配置中的 ContextForge)的职责。两者旨在并行运行。

状态

设计锁定于 2026-08-17(DESIGN.md v0.5)。读取路径、角色(§6.1)、validate / where_used 和 materialize 已实现。变更工具要等到首次内部试用之后。当前下一步:STATUS.md。

Related MCP server: Home Lab Context MCP

安装

需要 Python 3.11+ 和 uv。

cd insitu
uv sync
uv run pytest
uv run insitu

uv run insitu 在 stdio 上启动 MCP 服务器。

保险库根目录

每个进程一个保险库,顺序如下:

  1. INSITU_HOME

  2. --vault /path/to/vault

  3. ~/.insitu

一个新的保险库只是磁盘上的文件夹(stanzas/、projects/、可选的 config/surfaces.yaml)。本仓库中的 examples/vault/ 是一个虚构的示例,你可以指向它:

uv run insitu --vault examples/vault

不要将个人保险库复制到本公共仓库中。

将 MCP 服务器添加到宿主

有关 Cursor、Claude Code 和 Grok 的片段,请参阅 install/mcp.json.examples.md。典型形式如下:

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

复制三个路由器(一次性,用户全局)

路由器告诉宿主 Insitu 的存在。它们不是项目协议。

宿主

复制自

复制到

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

可选:将 install/AGENTS.md 手动粘贴到宪法文件中。materialize 从不写入 AGENTS.md、CLAUDE.md 或 CLAUDE.local.md。

使用 config/surfaces.yaml(grok、claude、cursor)在保险库中启用宿主适配器。然后在项目检出目录中调用 materialize。它将写入 PROTOCOL.md 以及 .grok/rules/、.claude/rules/ 和 .cursor/rules/ 下的适配器文件。

预期用途

# 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?

开发

uv sync
uv run pytest
uv run insitu

Python 3.11+,FastMCP。如果你是正在本仓库工作的智能体,请参阅 AGENTS.md。

许可证

MIT。参见 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.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers