Read-only MCP and Copilot integration¶
Read-only MCP and Copilot integration¶
The v0.3 MCP adapter exposes exactly two tools: inventory and
prepare_transfer. It runs locally over stdio, without a terminal, and uses the
bounded image API. It does not extract, move, copy, delete,
approve or execute a plan, create a destination, or write pictures.log.
OS-managed access-time bookkeeping may still change during reads.
This is the v0.3 candidate contract, not an announcement of a published
release. The implementation is merged and hosted Windows/Linux checks passed;
authenticated Copilot acceptance and a human release decision remain pending.
See Acceptance and release gates.
The existing archivist CLI and its approval rules are unchanged.
There is no AG-UI, model-provider or agent-framework dependency.
Runtime and installation boundary¶
Python 3.10 or later on Windows or Linux.
uv, including
uvx, and Git for a direct Git source.The optional
archivist[mcp]extra installs the official Python SDK,mcp>=1.28,<2. Ordinary CLI installations do not need MCP.archivist-mcpis the separate console entry point;--stdiois optional and stdio is the only supported transport. It is not a switch onarchivist.
For development in this checkout, after installing the optional extra:
uv run --extra mcp archivist-mcp --help
uv run --extra mcp archivist-mcp --stdio --source-root "C:\photos" --destination-root "D:\collections"
The second command waits for an MCP client on stdin; it is not an interactive photo command. Configure a client to launch it rather than typing requests in a terminal.
Public launches use a tested immutable commit¶
Do not use bare uvx archivist: that PyPI name must not be assumed to belong to
this repository. These examples select the repository explicitly. Do not replace
the pin with main, another branch, a mutable tag, or an abbreviated SHA.
# Merged implementation from PR #30; tested on Windows and Linux.
$env:ARCHIVIST_REVIEWED_COMMIT = "d92909fccb11624c490781df2d6a4d3eac719658"
if ($env:ARCHIVIST_REVIEWED_COMMIT -notmatch '\A[0-9a-fA-F]{40}\z') {
throw "A reviewed immutable server commit is required."
}
$package = "archivist[mcp] @ git+https://github.com/CoffeesoftDotDev/archivist.git@$env:ARCHIVIST_REVIEWED_COMMIT"
uvx --from $package archivist-mcp --stdio --source-root "C:\photos" --destination-root "D:\collections"
The sample pins the public merge commit from
PR #30, containing the
extra, entry point, adapter and tests. It does not track later changes on main.
Review the selected code and access policy before using your own collections;
replace the sample paths with existing directories you explicitly authorize.
Selecting this commit does not approve a transfer or publish a v0.3 release.
For a later revision, record its full SHA and acceptance evidence rather than
substituting a branch or tag.
First use normally needs network access to GitHub, package indexes and possibly
Python distribution downloads. uv creates environments and caches outside the
collection: collection read-only does not mean installation writes nothing.
Offline startup requires a compatible installed Python, uv/Git and the exact
source revision, build dependencies and resolved runtime dependencies already
available in uv’s cache. Warm and test that exact command on the target machine
before disconnecting; uvx --offline --from $package ... fails rather than
fetching missing material. A full source pin does not lock every transitive
dependency; retain resolved versions with acceptance evidence.
Operator configuration¶
Both allowlists are configured at process startup, not by the model. At least
one --source-root is required to start the adapter.
Repeat --source-root PATH or --destination-root PATH for separate authorized
trees. Configured roots must be existing directories. An absent destination
allowlist denies previews requiring destination access; it does not prevent
source-only inventory. A proposed destination may not exist yet, but must be
inside a configured destination root. Source and destination must be disjoint.
Use absolute paths to avoid process-working-directory ambiguity.
An empty facade allowlist denies that access; the server rejects startup without a source root rather than adding one. There is no whole-drive or home-directory fallback. Link/junction/reparse paths and escapes are rejected by the facade. These checks are application policy, not an OS sandbox: restrict process privileges and protect roots from concurrent replacement.
Startup limit flags are the ReadLimits field names with underscores replaced by hyphens:
Flag |
Default |
|---|---|
|
10,000 |
|
100,000 |
|
100 |
|
65,536 |
|
8,388,608 |
|
33,554,432 |
|
16 |
|
300 |
Values must be positive integers, and archive entries cannot exceed the existing
100,000-entry safeguard. Nested ZIP depth, payload and expansion limits still
apply. Byte budgets bound encoded retained observations, not total process
memory or every transient ZIP-parser allocation. Tool arguments cannot change
roots, limits or startup settings. CLI ARCHIVIST_* apply/logging settings do not
grant execution authority to this adapter.
Tool and page contract¶
Use MCP initialization followed by tools/list as the runtime machine-readable
inventory. It advertises each tool’s input and output JSON Schema.
Export machine-readable schema evidence through the implementation as described
under Contributor checks; do not maintain a second,
hand-written JSON Schema in a plugin.
Tool |
Initial request |
Continuation |
|---|---|---|
|
|
|
|
|
|
extensions is a list of individual supported extensions, not the CLI’s
comma-separated --filter string. Omit it for all supported images; an empty
list or unsupported extension is an error. Initial calls and cursor-only calls
are distinct: do not resend roots, filters, mode or schema version with a cursor.
There is no apply, approval, execution, arbitrary-shell or cleanup field/tool.
Unknown action fields are rejected, not silently ignored.
Successful tool results reuse the ReadPage JSON envelope: schema_version,
snapshot_id, operation (inventory or transfer), inventory_complete,
records, and next_cursor. Read the structured result, not a reconstructed
display string. Records distinguish summaries, images, archives, problems,
notices, transfers, extraction headers and extraction members.
Follow next_cursor with the same tool and a cursor-only request until it is
null. Pagination completion and inventory completeness are different:
inventory_complete=false is partial discovery, never a successful zero-match
answer. Drain all pages before presenting a complete inventory or effects
manifest. A transfer page without its later extraction members is not the whole
preview. Preparation refuses incomplete discovery.
Cursors are opaque, instance-bound and short-lived. Paging does not renew expiry. Changed source/destination state invalidates an observation. On stale, expired or invalid cursors, start a new initial request; do not combine pages from different observations. Capacity and size failures require narrowing the request or operator review, not model-driven policy expansion.
Schema/protocol failures and tool failures are errors, not success-shaped empty
collections. Inspect MCP isError and structured diagnostics where provided;
do not assume every validation error has the same envelope as ReadPage.
The shared API documents stable failure codes and incomplete-inventory problems.
stdout belongs exclusively to MCP; diagnostics go to stderr.
Example tool arguments¶
These JSON objects are tool arguments, not complete JSON-RPC messages or terminal commands. A compatible MCP client initializes the server and calls the named tool.
Start with inventory:
{
"root": "C:\\photos",
"extensions": ["jpg", "arw"]
}
After reading a complete inventory, call prepare_transfer with the same
source and filter:
{
"root": "C:\\photos",
"destination": "D:\\collections\\selected",
"mode": "copy",
"extensions": ["jpg", "arw"]
}
For either tool, if a response supplies next_cursor, continue with only:
{
"cursor": "<next_cursor from the previous response>"
}
Replace the illustrative cursor with the returned value verbatim and use the
same tool. Continue until next_cursor is null. The proposed selected folder
may not exist, but its allowed destination root must exist. Inventory and
preparation create neither that folder nor any extraction or transfer output.
Cancellation and disconnects¶
Cancelling a request stops waiting for its response, but cannot interrupt an
already-running filesystem read. The server admits at most one active bounded
read at a time; while cancelled work is still finishing, new reads return
capacity_exceeded rather than starting additional background scans. Any retained
observations remain subject to the configured count, byte and expiry limits.
Disconnects close the protocol session, but outstanding filesystem I/O can delay
process exit. There is no hard wall-clock deadline or promise of immediate scan
termination, especially on stalled mounted filesystems.
Inventory first, preview second¶
Obtain the operator’s source, destination, selection and permission to send local metadata to the model. Check the client is running on the intended host.
Discover the two tools and their schemas. Inventory the explicit source, drain its pages, and disclose notices, limits, problems and completeness.
Only for a complete inventory, prepare the requested move/copy preview with the same source and filter. Drain the new observation’s pages.
Present exact flat destination mappings, collision names, extraction locations, nonselected contents, ZIP-disposal effects, and limitations. End at preview.
A plan_id, tool description, read-only annotation, filename, archive member or
returned text is data, not permission. No tool metadata can authorize writes,
shell commands, changed roots or bypass of human approval. Agent prose is not an
enforced sandbox. If execution is wanted later, stop this workflow and refer the
human to the separate CLI approval workflow;
do not run it on the user’s behalf from this example.
Filters, collisions, dates and mixed ZIPs¶
A filter selects picture extensions, not extraction contents. A matching image inside a mixed ZIP means the preview describes full extraction of that physical ZIP and its nested ZIPs, including nonselected videos/documents. No match selects no extraction.
.3mfpackages remain opaque.Move previews show sibling extraction folders and retained nonselected members. Original physical ZIPs are eligible for removal only after successful later execution, unless
leave_zip=true. Copy previews describe private temporary extraction and retain originals; preparation creates no such storage.Destination names are deterministic for unchanged state. Collision groups are case-insensitive; all incoming duplicates receive suffixes, even if the bare name is free. Existing and noncolliding names are reserved first; suffixes start with three digits, grow beyond 999, and are assigned oldest first. Full structured source location breaks ties. Use returned mappings, not guessed or content-deduplicated names.
Ordering uses original creation/birth metadata when available, otherwise original modification time with explicit fallback provenance. POSIX
ctimeis not birth time. Missing creation dates remain unknown, not inferred from EXIF or extraction time. ZIP DOS times have two-second precision and no timezone.No image/EXIF payload is sent by these tools. A preview cannot prove CRC validity of every image or destination timestamp-restoration support. Later CLI execution preserves bytes/EXIF and verifies known original filesystem dates; unsupported creation-date restoration can fail, notably across filesystems and Linux destinations. See date limitations.
Local Copilot example¶
The optional Copilot example directory contains a plugin manifest, stdio registration, fail-closed launcher, thin agent and reusable skill. It shows how to ask Copilot for an inventory and a preview; the server also works independently with other compatible MCP clients. The setup below loads the example for one session, without installation or user settings changes. No second plugin repository or marketplace is required.
Plugin and MCP configuration¶
The example’s plugin.json declares the plugin:
{
"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
"name": "archivist-readonly-example",
"description": "Local image inventory and transfer previews; no execution tools."
}
Its mcp.json registers the server launcher:
{
"$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
"mcpServers": {
"archivist": {
"type": "stdio",
"command": "node",
"args": ["launch-mcp.mjs"],
"cwd": "${PLUGIN_ROOT}"
}
}
}
Copilot supplies ${PLUGIN_ROOT} as the working directory. The Node.js 20+
launcher reads the explicit pin and roots from environment variables, checks
them, then starts uvx without a shell. It does not rely on arbitrary variable
expansion inside the MCP JSON. Keep the
launcher, agent and skill files
together; the two manifests alone are not the complete plugin.
Load the example for one session¶
From the repository root in PowerShell, with uv/uvx, Git, Node.js 20+ and a compatible local Copilot CLI available:
$env:ARCHIVIST_REVIEWED_COMMIT = "d92909fccb11624c490781df2d6a4d3eac719658"
$env:ARCHIVIST_SOURCE_ROOT = "C:\photos"
$env:ARCHIVIST_DESTINATION_ROOT = "D:\collections"
copilot --plugin-dir .\examples\copilot
Replace both folder paths with existing, disjoint directories you authorize. The environment settings last for the current shell and are inherited by the session launcher; they do not install a plugin or alter Copilot user settings. On Linux, set the same three variables in your shell using native absolute paths, then load the same example directory.
Ask for inventory and preview¶
Inspect /mcp, /agent and /skills in the local session, select
archivist-preview, and request, for example:
Inventory JPG and ARW pictures under my configured source, including nested ZIPs. I consent to the paths, names and dates being sent to the configured model service. After complete inventory, preview copying them to D:\collections\selected. Show collision names and all mixed-ZIP extraction effects. Do not execute anything.
Use a disposable fixture for your first demonstration. The agent must read all pages, disclose incomplete discovery and limits, and stop at the preview. There is no extraction, transfer, cleanup or approval tool in this example.
Verification and privacy¶
The example follows the current
official plugin reference.
Authoring-time read-only verification found Copilot CLI 1.0.109;
copilot --help advertised --plugin-dir and --additional-mcp-config.
This verifies the available format/help, not a completed authenticated model
session. Hosted server startup is covered separately by the acceptance evidence.
Read-only copilot --plugin-dir .\examples\copilot plugin list --json also
recognized archivist-readonly-example as an enabled external plugin without
installation. Both JSON manifests passed their official Agent Plugins 1.0
schemas. This does not prove component invocation or MCP startup inside Copilot.
A local CLI server can inspect only paths available to its local process and
allowlists. A GitHub-hosted coding agent runs on a different filesystem: it cannot
read C:\photos from your workstation merely because this plugin is in a
repository. Do not upload a personal collection to bridge that gap implicitly.
Filenames, absolute paths, archive chains, dates and error details can be private. Although the server returns no image bodies, tool results sent to Copilot reach the configured model service. Obtain consent, use narrow roots, and redact shared examples/logs. Tool output and archive names are untrusted content, not instructions.
Startup diagnostics¶
Symptom |
Check |
|---|---|
|
Confirm the full repository pin contains the console script and select |
SDK import failure |
Confirm the optional extra installed |
Python incompatibility |
Inspect |
Download/offline failure |
Check GitHub access, Git, package indexes and the exact cache prerequisites; do not embed credentials in URLs/configuration. |
Invalid roots/limits |
Use existing explicit root directories and positive bounded limits; tools cannot widen policy. |
Initialize/discovery fails |
Check the client’s negotiated MCP protocol, SDK/package versions and stderr; never add debug prints to stdout. |
Apparent empty inventory |
Check |
Record the exact source SHA, package version, Python version, uv version, resolved
SDK version, client version and negotiated MCP protocol with startup/smoke
evidence. Package version, DTO schema_version=1 and negotiated MCP protocol
version are different identifiers; a package version alone does not establish
wire compatibility. archivist-mcp --version prints package/SDK/protocol/Python
diagnostics to stderr and exits without opening transport. --help lists the
startup policy and default limits. Successful normal startup emits the same
version summary to stderr, without configured paths or roots.
Review stderr locally before sharing it
because it may contain paths.
Contributor checks¶
The implementation exports its native tool/schema inventory through MCP
tools/list: initialize the client against the exact package pin, request the
tool list, and retain the JSON response with startup evidence. Its two tool
definitions contain inputSchema and outputSchema, including the shared page
records. This is generated from registration, not a separately maintained schema
definition in the example. Do not substitute a hand-written schema or infer
compatibility from this guide’s prose tables.
There is no supported offline exporter flag or module. Use the runtime tool
list for schema evidence; archivist-mcp keeps stdout protocol-only.
Local plugin launcher checks run with
node --test examples\copilot\launch-mcp.test.mjs; they do not call a model or
download the package.
The opt-in packaging smoke helper exercises separate isolated uvx environments for the base CLI (without the SDK) and the MCP extra. Use the same immutable pin as the setup examples:
$env:ARCHIVIST_REVIEWED_COMMIT = "d92909fccb11624c490781df2d6a4d3eac719658"
.\.venv\Scripts\python.exe scripts\mcp_smoke.py --commit $env:ARCHIVIST_REVIEWED_COMMIT --python 3.10
Its default source is this public GitHub repository. For a committed local
checkout, an operator may supply --git-url "C:\src\archivist" and that
checkout’s reviewed full commit instead; an uncommitted server is not included
in a Git pin. --lane cli or --lane mcp limits the helper to one lane. These
are opt-in installation/network checks, not part of ordinary pytest invocation.
The dedicated .github\workflows\mcp.yml targets Windows/Linux with Python
3.10/3.13. Its successful hosted run is linked below; merely adding a workflow
file is not acceptance evidence.
With documentation dependencies already installed:
uv run --no-sync sphinx-build -b html -W --keep-going docs docs\_build\html
Acceptance and release gates¶
This checklist is a handoff, not release authority. Local results are reported separately from hosted results; unchecked gates must not be inferred as passed.
Local documentation/example validation on Windows used Copilot CLI 1.0.109,
Node.js 24.19.0 and Sphinx 8.2.3: four launcher tests passed, official manifest
schema checks passed, session-only plugin mount discovery passed, and the strict
Sphinx HTML build passed. Adapter --help and --version were also inspected;
the current development package still reported 0.2.0, not a released v0.3.
These checks do not replace the hosted or human checks below.
Final local Windows validation for PR #30 passed 545 regression tests with four platform-dependent skips using SDK 1.30.0. SDK-free isolated Python 3.10.21 and 3.13.15 environments each passed 444 tests with 14 skips. An earlier minimum-SDK compatibility run passed all 106 adapter/stdio/packaging tests on Python 3.10 with SDK 1.28.0. These local results are distinct from the hosted runs below.
Hosted evidence for the sample pin¶
All runs below tested merge commit
d92909fccb11624c490781df2d6a4d3eac719658 from PR #30:
Hosted run |
Coverage |
Result |
|---|---|---|
SDK contracts and clean public-source uvx startup on Ubuntu/Windows, Python 3.10/3.13 |
Passed all eight jobs |
|
SDK-free CLI regressions on Ubuntu/Windows, Python 3.10/3.13; non-root Docker build and smoke |
Passed |
|
Strict documentation build and deployment from main |
Passed |
|
Python and Actions analysis |
Passed |
The clean uvx probes used Python 3.10.22 and 3.13.18 on Ubuntu, and 3.10.22 and
3.13.17 on Windows. Each ordinary CLI environment contained no MCP SDK.
The MCP SDK/client was 1.30.0; startup reported Archivist 0.2.0 and protocol
2025-11-25. Probes discovered exactly the two tools, paged disk/ZIP inventory and
previews, rejected an apply field and left fixture snapshots unchanged.
The SDK-contract jobs separately covered nested/mixed ZIPs, unsafe requests,
stale observations, cancellation/disconnection and no-write snapshots.
These results establish server and transport acceptance, not authenticated Copilot agent behavior or release approval. Keep the selected SHA with its evidence and rerun smoke checks if the deployment pin changes.
Remaining release checklist¶
[x] Immutable public server commit recorded after PR #30 merged; samples use that exact CI-tested SHA.
[x] Clean-environment pinned
uvxstartup on hosted Windows and Linux records package/Python/SDK/client/protocol versions and exactly the two advertised tools.[x] Real stdio initialization, schema discovery, tool calls, bounded paging, cancellation/disconnection and clean shutdown pass on the supported matrix.
[x] Disposable disk and nested/mixed-ZIP fixtures prove inventory and preview cause no source/destination/report/staging writes (apart from OS read bookkeeping).
[x] Unsafe paths, invalid fields/filters, incomplete discovery, no matches, collisions and stale/expired cursors are covered.
[x] Ordinary CLI installation and regressions pass without MCP dependencies; Windows/Linux CLI Python 3.10/3.13, Docker and Pages checks are preserved.
[ ] Human verifies local Copilot tool discovery, inventory then preview, privacy disclosure and no execution claims using the reviewed pin.
[ ] Human reviews AI-assisted documentation and accepts remaining platform, dependency-resolution and timestamp limitations.
[ ] Authorized maintainer decides whether to release v0.3; version metadata, release notes and tag are handled through the repository release procedure.
For a release decision, retain hosted job links and limitations alongside the
reviewed SHA. Version changes in pyproject.toml and src/archivist/__init__.py
must agree; refresh the lockfile when dependencies change. Re-run pinned smoke
checks against the intended release commit before approving a tag. Do not
publish a distribution based on an unverified ownership assumption. A completed
implementation, this checklist, or creation of backlog items does not publish
or approve a release.