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

```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:

```powershell
[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
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:

```powershell
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.