Insitu
Insitu is a local MCP server for managing a vault of reusable AI guidance/skills and composing/materializing per-project protocols for AI hosts.
Inspect vault state: resolve project protocols, list/get stanzas (articles), roles, projects, on-demand guidance, skills, packs, and where-used references; report protocol sizes and status.
Validate vault health and inspect operator classes/admin registrations.
Create/update/delete stanzas (articles) and log why/provenance; link or unlink them to project maps as core or on-demand.
Manage roles: create/update/delete role packs and preview/confirm member changes.
Manage project maps: create/update/delete projects, choose core/on-demand stanzas, roles, skills, notes, and global inclusion.
Manage skills: create/update/delete, link/unlink to projects, inspect usage and associated files.
Materialize a project: write PROTOCOL.md and configured host adapters, plus copy mapped skills into host skill directories.
Manage packs: list/get shelf contents, fetch packs, install/uninstall whole capabilities, individual stanzas, or skills for a project.
Administer access: grant/revoke admin or bound operator classes, with preview/confirm safeguards for destructive operations.
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., "@Insitu materialize the protocol for this project"
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.
Insitu
Insitu keeps your AI instructions and skills in one vault, and every project subscribes to exactly the set it needs, so guidance stops drifting between projects.
The problem
You already have directions for how an agent should work with you. The pain is reuse. The same guidance needs to show up in more than one place, but not the same set every time. Copies drift. A new repo starts without the ones you meant to bring. You notice after the agent has already gone the wrong way.
Related MCP server: Home Lab Context MCP
What you get
Write it once. Each piece of guidance is one markdown file in one vault. Fix it there and every project that uses it gets the fix.
A deliberate set per project. Each project picks its own mix: always-loaded guidance, guidance pulled only when the work needs it, bundled roles, and
/nameskills. Not a paste of everything.Every AI client, its own format. Insitu writes the project's set into the files each client already loads. Name the clients you use once, and every project adapts to each.
Guardrails on shared rules. A rule that other projects depend on can't be quietly edited from inside one project.
A size check. Reports tell you when a project's loaded guidance has grown heavier than it should be.
A day with it
This walks through the sample vault that ships in examples/vault, with two made-up repos, harbor-notes and river-ledger.
Each repo carries a different set from the same vault. summary-first, how the agent reports back, is global guidance: river-ledger takes it, harbor-notes opts out. small-diffs is always loaded in harbor-notes but only on demand in river-ledger. river-ledger also wears the clerk role for its bookkeeping guidance and maps a /close-books skill that harbor-notes never sees.
In the morning you ask the agent in river-ledger to materialize. Insitu writes the composed set into the files your AI client loads, and copies /close-books into that client's skill folder. Switch clients after lunch and the same set is waiting there, in that client's format.
Late in the day you decide small-diffs should be stricter. You edit the one article in the vault, and each repo that carries it picks up the change the next time it materializes. With operators set up, an attempt to make that edit from inside harbor-notes is refused, because river-ledger composes the article too.
Part of Domain Prime
Insitu is one of four engines in Domain Prime, a local-first system for running many AI projects as a tree. Every chair in the tree, the top included, can subscribe to its own set of instructions from one shared vault. It also runs on its own: point it at any folder and it works without the rest. Terms like chair and nexus are defined in the glossary.
How it works
Insitu is a portable MCP server. One vault holds the reusable pieces of how an agent should work with you. A project map names which of those pieces apply in this folder. The server composes them into a protocol and writes that core into files the host already loads.
It is not a wiki, not a bulletin, and not a model of a codebase. It does not run git and it does not use the network.
The vault holds five kinds of thing:
Articles. Standing guidance (tone, method, review, identity that changes how the agent operates). One markdown file each.
Roles. Named packs of articles and skills a kind of project includes as a unit (
node,repo, and the like).Projects. A map per working folder: core articles, on-demand articles, imported packs, and skills.
Skills. Procedures the host should expose as
/name. Carried by a role or mapped on the project. Copied into host skill directories onmaterialize. Not concatenated into the protocol.Packs. Versioned capabilities authored outside the vault. Each Domain Prime product ships one as its public contract (insitu-core, envoy, context-forge, brain-forge). Installed onto a shelf, then imported by a project.
How they fit together:
An article is one markdown file of standing guidance.
A role is a named, ordered pack of articles and skills a project can include as a unit.
A project map selects articles as core (always loaded) or on-demand (pulled when the work needs them), plus imported packs and mapped skills.
A protocol is composed, never a catalog row.
materializewritesPROTOCOL.mdplus host adapters so the core is in the session.resolve_protocolinspects the same composition.A skill is a procedure the host discovers as
/name.materializecopies composed skills into the project skill directory each enabled host names inplatforms.yaml. With no environment file, no skill directory is created.A pack is a versioned bundle on the vault shelf (
library/<id>/<version>/).install_capability/install_articlepull it and write this map. A single-article install may land incoreoron_demand.
Size reports on articles and on the composed protocol tell you when to trim. Skills have their own size summary. They do not go into the protocol token count.
Install
Requires Python 3.11+ and uv.
git clone https://github.com/srmackey/insitu.git
cd insitu
uv sync
uv run pytestuv run insitu starts the server on stdio through FastMCP 2. There is no published package. Clone and run from the checkout.
Vault
One vault per process, resolved in this order:
INSITU_HOME--vault /path/to/vault~/.insitu
A vault is folders on disk (articles/, skills/, provenance/, projects/, optional roles/, library/, and config/). This repo ships a sample vault:
uv run insitu --vault examples/vaultKeep a personal vault outside the checkout.
Add the server
The procedure is install/README.md. The block is install/mcp.json.examples.md. Host files come from platforms.yaml next to nexus.md. With no environment file, user-global host config is left alone, and project instructions land on agents through materialize.
command: uv
args: ["run", "--directory", "/path/to/insitu", "insitu"]
env:
INSITU_HOME: /path/to/your/vaultA router tells the host that Insitu exists. It is not the project protocol. The install pass places it from install/routers/. Optional: paste install/AGENTS.md into a constitution file by hand. materialize never writes CLAUDE.md or CLAUDE.local.md. It writes the project AGENTS.md only when that file is missing or already carries the Insitu stamp, which is what a checkout gets when platforms.yaml is absent.
When INSITU_ROOT points at a folder with nexus.md and platforms.yaml, enabled in that file chooses the hosts, and each stored definition says where the adapter and the skills go. From an existing project checkout, call materialize. That writes PROTOCOL.md, one adapter for each definition it can apply, and skill copies into each project skill path that definition names. A missing environment file writes AGENTS.md (when Insitu may own that file) and does not invent host skill trees. If the folder is missing, the call is refused (working_folder_missing); it does not create one.
Working with an agent
Once the server, vault, and router are in place, you talk to the agent in the project folder. Outside an install, Insitu keys the project off that folder's name. When INSITU_ROOT points at a folder with nexus.md, the key is the address from that file.
First time in a checkout. Ask the agent to materialize this project's protocol. That writes PROTOCOL.md, the host adapter files, and mapped skill copies. With no platforms.yaml, the adapter is AGENTS.md when that file is missing or already stamped. CLAUDE.md is not that output. Later sessions load the core on their own. Do not edit the generated protocol or skill files. Change an article, skill, or the project map in the vault, then materialize again.
Day to day. The core is already in the session. Treat it as binding. Mapped skills are already in the host skill directories; treat /name as binding. Some articles are only on-demand: listed, not loaded. When the work needs one, ask the agent to pull it. You can name the guidance ("use summary-first") instead of a path.
A new project. Ask what articles, roles, skills, and packs exist. Pick the set this project should carry. Install a capability if this folder should use a whole pack. Then materialize. The point is a deliberate subset, not a paste of everything.
When something feels off. If the protocol is missing, stale, or heavier than it should be, ask the agent for Insitu status of this folder (project_status) or to inspect the composition and the size report. Rematerialize after you trim or change membership.
Add or update. If you find yourself repeating instructions, name and create a new article (or a skill, if it should be a /name procedure). Link it to one or more roles or projects. Instructions not working as expected? Find the articles or skills in use and update the right one.
Tools
Forty-five tools. The list, the hint set on each one, and what it returns are in docs/tools.md.
On initialize the server returns a short operating note: session start is resolve_protocol to inspect, and materialize writes the composed protocol. That note lives in the server. This page does not repeat it.
Every mutating tool takes working_folder. A bound chair (the default) may
write only its own map. Outside an install that key is the folder's basename.
When INSITU_ROOT points at a folder with nexus.md, the key is the address
from that file, and a unique basename still resolves. An admin chair may
name another key in its scope: any key for the top nexus, and its own address
plus the addresses under it for any other admin.
Articles, roles, and skills belong to no single map, so they are gated by reach
instead: creating is always allowed, and editing or deleting one is refused once
a map other than yours composes it. Editing a role is the sharp case, since its
membership reaches every map that carries it. A vault with no
config/operators.yaml runs pre-init: writes go through as before and the
result says how to fix it.
insitu init --admin <project-key> # register the first admin; refuses if one exists
insitu operators # show the config
insitu # start the MCP server (unchanged)Trust boundary
Transport is stdio. The host starts a local process as the user who launched it.
The process reads and writes the vault (
INSITU_HOME, or~/.insitu).materializealso writes generated files into the working folder the caller names, and only when that folder already exists.It does not run git, it does not start a shell, and it does not use the network.
It does not take a credential.
The same boundary, and how to report a vulnerability, is in SECURITY.md. How the system is structured is in DESIGN.md. What moved between versions is in CHANGELOG.md.
Develop
uv sync
uv run pytest
uv run insituLicense
MIT. See LICENSE.
Available Tools
44 toolscreate_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
link_skillB
Add a skill to a project's skills list. Writes now. Does not edit role files.
Inputs: project (required), skill_id (required), working_folder (required). Returns: object
link_stanzaA
Add a stanza to a project's core or on-demand list. Does not edit role files.
Inputs: project (required), stanza_id (required), working_folder (required), target. 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
unlink_skillC
Remove a skill from a project's map. Writes now.
Inputs: project (required), skill_id (required), working_folder (required). Returns: object
unlink_stanzaC
Remove a stanza from a project's map. Does not edit role files.
Inputs: project (required), stanza_id (required), working_folder (required). 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
Scored across 44 tools
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.
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.
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.
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
Hosted MCP server and Agent Skills for specs, engineering threads, and project memory.
The Stytch MCP server is a reference implementation that demonstrates remote MCP server authentication and authorization using Stytch Connected Apps. It provides OAuth 2.1-compliant authorization (including PKCE), Dynamic Client Registration, and validates Stytch-issued access tokens to enable AI agents to securely interact with external services through permissioned access, supporting scopes like openid, email, profile, and manage:project_data.
MCP Server for an Agent Task Marketplace
A MCP server built for developers enabling Git based project management with project and personal…
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceMCP Server for AI agent identity and authorization. Create, verify, and manage agent identities with trust scores and scoped authorization tokens.48 PyPIMIT
- AlicenseNot gradedqualityDmaintenanceA storage-backed MCP server for sharing durable project context between trusted coding agents, with project discovery, optimistic concurrency, and timestamped handoffs.Apache 2.0
- AlicenseNot gradedqualityCmaintenanceMCP server that gives AI agents a durable identity, persistent browser, memory, and coordination tools, enabling them to maintain state across sessions and act on the live web.3MIT
- AlicenseNot gradedqualityBmaintenanceMCP server for universal multi-agent communication, enabling agents to register, send/receive messages, manage tasks, and coordinate via role-based routing with project isolation.6 npmISC