ArchLog MCP

ArchLog MCP is a Windows-first local STDIO MCP server for architecture-guided software release-note generation. A user supplies a public GitHub C/C++ repository and two Git references; an agent can start the analysis, monitor the persistent job, and return the generated traceable release-note path.

This repository is a self-contained source distribution. It includes the pinned ArchLog runtime snapshot, ENRE-CPP JAR, and the SemArc-RAG runtime source under runtime/archlog. It does not depend on a sibling ArchLog checkout or a prebuilt SemArcArcRN.exe directory.

Current support

• Windows x64

• Python 3.12 x64

• Java 17 or newer and Git on PATH

• Public HTTPS GitHub repositories

• C and C++ repositories

• Chinese release-note output

• SiliconFlow model deepseek-ai/DeepSeek-V4-Flash

• SILICONFLOW_API_KEY from the user's environment

• Optional but strongly recommended GITHUB_TOKEN

SemArc runs from the committed SemArc_RAG/run_for_arcrn.py source entrypoint and uses its own depends dependency backend. ENRE-CPP remains independent ArchLog change evidence.

Install from source

Clone this repository, then run the supported installer from PowerShell:

git clone https://github.com/<owner>/ArchLog-MCP.git
cd ArchLog-MCP
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\install-from-source.ps1

The installer is idempotent. It creates .venv, installs the fully resolved runtime versions from requirements/source-runtime.lock.txt, installs required NLTK data, and performs an MCP environment check. It never asks for, writes, or prints API keys. Dependency downloads can take several minutes.

Set secrets in the user environment before launching the agent, then restart the agent so it inherits them:

[Environment]::SetEnvironmentVariable("SILICONFLOW_API_KEY", "<key>", "User")
[Environment]::SetEnvironmentVariable("GITHUB_TOKEN", "<token>", "User")

Register in Qoder

With Qoder CLI installed, register ArchLog for the current user:

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\register-qoder.ps1 -Scope user

Start a new Qoder Agent session or run /mcp reload, then ask Qoder to call archlog_check_environment. The template under adapters/qoder can be used in Qoder Settings > MCP when Qoder CLI is unavailable.

Let an agent install it

The following instruction is suitable for Qoder or another coding agent with a terminal. Replace the repository URL first:

Clone the ArchLog-MCP repository from <repository-url>. Read its README, run only scripts/install-from-source.ps1, preserve my existing environment variables, register the installed launcher as a user-level STDIO MCP, and run archlog_check_environment. Ask before downloading dependencies or changing agent configuration. Do not read, print, or store API-key values, and do not start an analysis yet.

Installation cannot be completely silent: the user should approve dependency downloads and the MCP configuration change.

MCP job contract

The server exposes:

• archlog_check_environment

• archlog_validate_request

• archlog_start_analysis

• archlog_get_status

• archlog_get_result

• archlog_get_failure_report

• archlog_resume_analysis

• archlog_cleanup_intermediate_results

Call archlog_start_analysis once with an idempotency key and poll no more often than next_poll_after_seconds. Only state=succeeded with a validated result is success. Process exit, directory presence, and partial stage output are not success indicators.

On Windows, the server first launches a worker with CREATE_BREAKAWAY_FROM_JOB. If an agent host such as Qoder forbids that flag, ArchLog MCP uses a transient per-job Windows Task Scheduler task instead. This keeps a long analysis alive after the short STDIO MCP request returns. The fallback writes only non-secret runtime paths to the job directory; API keys and GitHub tokens are never placed in task arguments or worker setting files. The worker removes its transient task registration when it reaches a terminal result. The current Windows user must be allowed to register limited, interactive scheduled tasks.

Confirmed cleanup permanently removes repositories, logs, external-analysis output, and intermediate pipeline artifacts. It retains final_release_note_traceable.md, manifest.json, request.json, and the job database record.

Repository layout

• src/archlog_mcp: STDIO server, persistence, validation, and job management

• runtime/archlog: committed analysis runtime snapshot

• runtime/archlog/third_party_tools/ENRE-CPP.jar: ENRE-CPP runtime

• runtime/archlog/third_party_tools/SemArc_RAG: headless SemArc source runtime

• requirements/source-runtime.lock.txt: pinned source-install dependencies

• scripts/install-from-source.ps1: supported source installer

• scripts/verify-install.ps1: MCP handshake and environment verification

• scripts/register-qoder.ps1: Qoder user/local/project registration

• scripts/sync_source_runtime.py: maintainer-only runtime snapshot generator

• scripts/runtime_overrides: lightweight compatibility files applied during runtime sync

• adapters: client configuration examples

SOURCE_RUNTIME_MANIFEST.json records the ArchLog source commit and SHA-256 of every committed runtime file. Maintainers regenerate the snapshot explicitly; end users do not need a second repository.

Mutable data and safety

The installation tree is treated as immutable during analysis. Jobs, cloned repositories, logs, checkpoints, and final release notes are stored under %LOCALAPPDATA%\ArchLog-MCP unless ARCHLOG_MCP_DATA_ROOT is set.

The controlled mock engine is available only through the explicit development setting ARCHLOG_MCP_ENGINE_MODE=mock. Production mode is the default.

Maintainer runtime refresh

After reviewing an authoritative ArchLog checkout, regenerate the committed runtime snapshot with:

python .\scripts\sync_source_runtime.py --archlog-root C:\path\to\ArchLog

Review the manifest and run the full test and isolated-install suite before committing the refresh. Do not commit .venv, caches, jobs, logs, experiment outputs, or the PyInstaller SemArc distribution.