MCP Agent Operations

mcp-agent-ops is a local stdio MCP server for deterministic agent-development operations that otherwise cause repeated shell and generated Python calls.

The service owns six capability groups:

• repository claims, worktree isolation, event journaling, archival, and contention reporting;

• reusable YAML and Markdown verification operations;

• recursive reference-data aggregation across authorized project and user folders;

• snapshot-based discovery and extension-aware batched loading of installed Agent Skills;

• Agent Skill validation; and

• evidence-based technology-skill detection.

The domain packages are independent of FastMCP. The installed mcp-agent-ops command starts the FastMCP stdio server, while mcp-agent-ops-claims preserves the direct claim CLI contract. Claim callers can own work-item activity, explicit or broad file scope, or one policy-bounded runtime resource with deadlines. Every checkout resolves disposable claim state to the primary worktree's ignored .agent-ops/resource-claim directory.

The claim engine, technology detector, and Agent Skill validator began as copies of the accepted dev-methodology implementations. See docs/reference/copied-scripts.md for exact provenance, intentional adapter changes, and compatibility coverage.

See docs/reference/mcp-tools.md for the complete small-call tool and resource surface.

Supported platforms

The stdio server, direct claim CLI, repository locking, reference and skill catalogs, verification, and technology detection run natively on:

• macOS with Python 3.11, 3.12, or 3.13;

• Linux with Python 3.11, 3.12, or 3.13; and

• Windows with Python 3.11, 3.12, or 3.13 in releases newer than v0.4.0.

Published release v0.4.0 predates native Windows claim locking. macOS and Linux remain supported by every published release. The optional shared multi-process evaluation audit uses POSIX file locking and remains limited to macOS and Linux; this does not affect ordinary MCP or claim operation on Windows.

Related MCP server: daimonos

Install the latest release

The supported distribution is the wheel attached to the latest GitHub Release. Do not install the generated source archive when only the runtime server is needed; the wheel excludes tests, documentation, and development dependencies.

On Windows, first confirm that the latest release is newer than v0.4.0. Then open PowerShell and install uv plus the GitHub CLI:

winget install --id astral-sh.uv -e
winget install --id GitHub.cli --source winget
gh auth login

Open a new terminal after WinGet changes PATH, then download and verify the latest release:

$releaseDir = Join-Path ([System.IO.Path]::GetTempPath()) "mcp-agent-ops-$([guid]::NewGuid())"
New-Item -ItemType Directory -Path $releaseDir | Out-Null

gh release download `
  --repo martinbechard/mcp-agent-ops `
  --pattern '*' `
  --dir $releaseDir

Push-Location $releaseDir
Get-Content .\SHA256SUMS | ForEach-Object {
  $expected, $file = $_ -split '\s+', 2
  $file = $file.TrimStart('*')
  $actual = (Get-FileHash -Algorithm SHA256 $file).Hash.ToLowerInvariant()
  if ($actual -ne $expected.ToLowerInvariant()) {
    throw "Checksum mismatch: $file"
  }
}
Pop-Location

Install the wheel with its tested, locked runtime dependencies:

$wheels = @(Get-ChildItem $releaseDir -Filter 'mcp_agent_ops-*.whl')
if ($wheels.Count -ne 1) {
  throw "Expected exactly one mcp-agent-ops wheel."
}

uv tool install `
  --python 3.11 `
  --with-requirements (Join-Path $releaseDir 'runtime-requirements.txt') `
  $wheels[0].FullName

mcp-agent-ops --version
mcp-agent-ops --identity-json
uv tool dir --bin

On macOS or Linux, install uv and an authenticated GitHub CLI, then download and verify the latest release assets:

release_dir="$(mktemp -d)"
gh release download \
  --repo martinbechard/mcp-agent-ops \
  --pattern '*' \
  --dir "$release_dir"

(
  cd "$release_dir"
  if command -v sha256sum >/dev/null; then
    sha256sum -c SHA256SUMS
  else
    shasum -a 256 -c SHA256SUMS
  fi
)

Install the wheel and its tested, locked runtime dependencies into an isolated tool environment:

uv tool install \
  --python 3.11 \
  --with-requirements "$release_dir/runtime-requirements.txt" \
  "$release_dir"/mcp_agent_ops-*.whl

rm -rf "$release_dir"

Running the same procedure after a newer release is published replaces the installed tool version. uv tool list reports the installed version and commands.

Verify the installed server package without starting stdio:

mcp-agent-ops --version
mcp-agent-ops --identity-json

The JSON identity includes a location-independent SHA-256 digest over installed runtime resources. Evaluation runners can pin both that runtime digest and the launcher executable digest instead of treating a small console-script wrapper as the server implementation.

Development

Python 3.11 or newer and uv are required for development.

uv sync
uv run pytest
uv run ruff check .
uv run mypy src

Hierarchical HTML rendering and durable plans

The package and MCP server expose render_hierarchy_html for turning nested mappings and sequences into responsive, self-contained HTML trees. The operation accepts in-memory data, JSON or YAML text, or an existing .json, .yaml, or .yml file.

from mcp_agent_ops.hierarchy import render_hierarchy_html

plan = {
    "Delivery": {
        "steps": [
            {"name": "Discover", "complete": True},
            {"name": "Implement", "complete": False},
        ]
    }
}

html = render_hierarchy_html(plan, title="Delivery plan")

For an agent-managed plan, create a durable JSON source beside the rendered HTML. The creation function returns the JSON path that every later mutation accepts:

from mcp_agent_ops.hierarchy import create_hierarchy_plan, update_hierarchy_plan

plan_path = create_hierarchy_plan(
    {"Delivery plan": ["Discover", "Implement", "Release"]},
    output_filename="delivery-plan.html",
    output_folder="reports",
)
update_hierarchy_plan(plan_path, "2", add_child="Write focused tests")
result = update_hierarchy_plan(plan_path, "2.1", completed=True)
if result.next_task is not None:
    print(result.next_task.identifier, result.next_task.label)

The MCP server publishes the same three names: render_hierarchy_html, create_hierarchy_plan, and update_hierarchy_plan. MCP file and folder paths must be absolute and resolve beneath MCP_AGENT_OPS_WORKSPACE_ROOTS. Creation returns the resolved JSON plan path. Update returns structured success, that same path, any automatically completed ancestors, and the next incomplete executable leaf with its parent context.

See the complete hierarchical HTML renderer reference for rendering, durable plan creation, exact item targeting, mutations, numbering, read-only browser markers, themes, validation, errors, regeneration behavior, and implementation links.

A runnable hierarchy gallery includes structured examples and a reviewable Markdown document outline. The examples use the packaged default, outline, and midnight themes plus a deliberately distinctive caller-supplied blueprint theme. Generate the live previews from the repository root:

uv run python examples/hierarchy-gallery/generate_gallery.py

Local MCP configuration

Configure an MCP host to run:

mcp-agent-ops

The server uses stdio by default. Configure these boundaries before exposing it to an agent:

• MCP_AGENT_OPS_SKILL_ROOTS contains precedence-ordered readable skill roots, separated by the operating system path separator. A root may contain child skill directories or may be one exact skill directory containing SKILL.md.

• MCP_AGENT_OPS_REFERENCE_ROOTS contains ordered readable user folders, separated by the operating system path separator. Every UTF-8 file beneath a configured folder is available by relative path.

• MCP_AGENT_OPS_DETECTION_REGISTRY identifies the trusted methodology-owned technology registry.

• MCP_AGENT_OPS_WORKSPACE_ROOTS contains allowed project and worktree roots, separated by the operating system path separator.

When the server starts with its working directory beneath a configured workspace root, it automatically overlays recursively discovered skills from <cwd>/.agents/skills and <cwd>/.codex/skills ahead of the configured user roots. The .agents project root has precedence over the .codex project root. Nested project skill directories are supported; duplicate skill names inside either one project root are rejected as ambiguous. skill_refresh rescans both project and configured roots.

If a discovered skill is a symlink whose SKILL.md resolves outside every configured root, catalog operations report the discovered manifest, resolved target, current roots, and an exact MCP_AGENT_OPS_SKILL_ROOTS value to authorize the target. Correct the setting and restart the MCP server before retrying. Other invalid catalog entries report the underlying manifest or read error and the containing root that must be corrected or removed.

skill_read and skill_load accept the optional include_extensions switch. Its default is false. When enabled for a base skill such as python, the loader searches the same precedence order for python.extension and appends that complete skill when found. The base and extension resolve independently, so either one can come from a project or configured user root.

When the working directory is beneath an allowed workspace, the server recursively publishes files beneath <cwd>/.agents and <cwd>/.codex/skills before files beneath the configured user reference folders. The server aggregates every matching relative path in search order with one newline between sources. Traversal and symlinks that resolve outside their selected folder are not published. reference_refresh rescans all reference folders.

Repository, project, verification, worktree, and validation paths supplied through tools must be absolute and resolve beneath their configured boundary. Name-based skill validation uses the same catalog lookup as skill loading. Explicit skill-validation paths may also target unpublished skills anywhere beneath the authorized working project, without adding those paths to catalog discovery. Catalog discovery, skill validation, and technology detection recheck every nested manifest, metadata file, source file, and supporting resource before reading it. The server rejects missing boundary configuration, traversal, and symlink escape rather than granting ambient filesystem access.

The reference and skill catalogs are built lazily and reused for the life of the server process. reference_refresh and skill_refresh atomically publish new snapshots after source files change. Technology registry configuration is also cached and takes effect after restarting the server. Claim state remains disk-authoritative and coordinates across server processes.

Junie on macOS

Junie reads MCP configuration from ~/.junie/mcp/mcp.json for user scope or .junie/mcp/mcp.json beneath one project. In the IDE, open Settings | Tools | Junie | MCP Settings.

Use the absolute executable directory reported by uv tool dir --bin. Replace YOUR_NAME and the workspace path with existing absolute paths:

{
  "mcpServers": {
    "mcp-agent-ops": {
      "command": "/Users/YOUR_NAME/.local/bin/mcp-agent-ops",
      "args": [],
      "env": {
        "MCP_AGENT_OPS_SKILL_ROOTS": "/Users/YOUR_NAME/.agents/skills:/Users/YOUR_NAME/.codex/skills",
        "MCP_AGENT_OPS_REFERENCE_ROOTS": "/Users/YOUR_NAME/.agents:/Users/YOUR_NAME/.codex/skills",
        "MCP_AGENT_OPS_DETECTION_REGISTRY": "/Users/YOUR_NAME/.agents/skills/detect-technology-skills/references/technology-skill-detection-registry.yaml",
        "MCP_AGENT_OPS_WORKSPACE_ROOTS": "/Users/YOUR_NAME/dev"
      }
    }
  }
}

macOS and Linux path lists use colons. On Linux, use the same configuration with Linux paths such as /home/YOUR_NAME.

Junie on Windows

Junie reads MCP configuration from %USERPROFILE%\.junie\mcp\mcp.json for user scope or .junie\mcp\mcp.json beneath one project. In the IDE, the same configuration is available under Settings | Tools | Junie | MCP Settings.

Use the absolute executable directory reported by uv tool dir --bin. Replace the example user and workspace paths with existing absolute paths:

{
  "mcpServers": {
    "mcp-agent-ops": {
      "command": "C:\\Users\\YOUR_NAME\\.local\\bin\\mcp-agent-ops.exe",
      "args": [],
      "env": {
        "MCP_AGENT_OPS_SKILL_ROOTS": "C:\\Users\\YOUR_NAME\\.agents\\skills;C:\\Users\\YOUR_NAME\\.codex\\skills",
        "MCP_AGENT_OPS_REFERENCE_ROOTS": "C:\\Users\\YOUR_NAME\\.agents;C:\\Users\\YOUR_NAME\\.codex\\skills",
        "MCP_AGENT_OPS_DETECTION_REGISTRY": "C:\\Users\\YOUR_NAME\\.agents\\skills\\detect-technology-skills\\references\\technology-skill-detection-registry.yaml",
        "MCP_AGENT_OPS_WORKSPACE_ROOTS": "C:\\Users\\YOUR_NAME\\dev"
      }
    }
  }
}

Windows path lists use semicolons. Restart Junie after saving the configuration, then confirm that mcp-agent-ops is active and exposes its tools in MCP Settings.

Evaluation runners may configure MCP_AGENT_OPS_AUDIT_LOG plus MCP_AGENT_OPS_AUDIT_ROOTS to create one exclusive digest-only JSON Lines tool-call trace. When a harness starts inherited MCP servers for a parent and subagent, set MCP_AGENT_OPS_AUDIT_SHARED=true plus a 32-character lowercase hexadecimal MCP_AGENT_OPS_AUDIT_SESSION_ID; each process then writes a separate random stream identity and process-local sequence into the same owner-only file under a POSIX file lock. Both modes record only canonical tool name, lifecycle status, call identity, sequence, and argument or result digests. Shared version-two records also carry the session and process stream identities, and their terminal records carry bounded canonical outcomes for supported deterministic operations. Reference loads record LOADED or REJECTED, and reference refresh records CATALOG or EMPTY. skill_validate records VALID or FINDINGS. These labels reveal no reference content, skill content, names, paths, or validation findings. The trace never stores arguments, returned content, prompts, or configured paths. Do not configure this trace for ordinary sessions that do not need evaluator-owned call evidence.

An evaluator can also set MCP_AGENT_OPS_REQUIRED_RUNTIME_DIGEST to the pinned value returned by --identity-json. The server checks it before importing FastMCP or starting stdio and fails closed when the installed runtime has drifted.

Create a release

Releases use semantic versions. The Git tag must be v followed by the exact project.version value in pyproject.toml; the release workflow rejects a mismatch.

1. Choose the next version and update project.version in pyproject.toml.

2. Refresh the lockfile and run the complete local verification:

   uv lock
   uv sync --locked
   uv run pytest
   uv run ruff check .
   uv run mypy src

3. Commit the version and lockfile, push main, and wait for its CI run to succeed:

   VERSION="$(sed -n 's/^version = "\([^"]*\)"/\1/p' pyproject.toml)"
   git add pyproject.toml uv.lock
   git commit -m "Prepare release v${VERSION}"
   git push origin main
   gh run list --workflow CI --branch main --limit 1

4. Tag the verified commit and push the tag:

   git tag -a "v${VERSION}" -m "Release v${VERSION}"
   git push origin "v${VERSION}"

5. Confirm that the Release workflow passed and the release is available:

   gh run list --workflow Release --limit 1
   gh release view "v${VERSION}"

The tag-triggered workflow reruns tests on Python 3.11, 3.12, and 3.13 before publishing the wheel, runtime-requirements.txt, and SHA256SUMS. Do not reuse or move a published version tag; increment the package version for the next release.

State ownership

Claim registries and event journals live beneath each target repository's primary-worktree .agent-ops/resource-claim directory, which projects ignore with the exact anchored /.agent-ops/resource-claim/ rule. Read-only status and reporting do not create absent state. A first mutating operation migrates only empty state from the rejected .codex/agent-claim root, preserves its history, writes the version-two canonical state marker, and installs incompatible markers at the old paths. Live legacy claims are drain-only through exact release. Once the complete marker is durable, normal claim operations require no access to .git or .codex. Reference and skill files remain authoritative in their configured scopes. Process-local catalog snapshots are read versions identified by digests, not independent state stores; publishing or restarting replaces them from disk.