Skip to main content
Glama
hongzhuan

ArchLog MCP

by hongzhuan
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python

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.

Related MCP server: DevForge-MCP

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.

Available Tools

3 tools
archlog_check_environmentA

Check the local ArchLog, ENRE-CPP, SemArc, Git, Java, data path, and LLM configuration without starting an analysis.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It correctly indicates the tool is non-destructive, but does not disclose failure behavior, permission needs, or output specifics.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence that is front-loaded with the verb 'Check' and lists specific items. No redundancy or wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given zero parameters and the presence of an output schema, the description is adequate. It covers the tool's purpose and scope without needing to detail return values.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are no parameters, so the baseline is 4. The description adds value by listing exactly what is checked, compensating for the lack of parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool checks multiple specific configurations (ArchLog, ENRE-CPP, SemArc, Git, Java, data path, LLM) and distinguishes from siblings by noting 'without starting an analysis', contrasting with archlog_start_analysis.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies use as a pre-flight check before analysis, but does not explicitly state when to use vs. siblings or provide exclusions. The distinction is largely implicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

archlog_start_analysisA

Start an asynchronous architecture-guided release-note analysis and return immediately with a persistent job ID. Poll with archlog_get_status; do not wait in this call.

ParametersJSON Schema
NameRequiredDescriptionDefault
base_refYes
head_refYes
repo_urlYes
idempotency_keyNo
output_languageNozh

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.8/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It accurately conveys that the call is asynchronous and returns immediately, implying no blocking. It does not mention authorization or side effects, but for a simple async initiation, this is adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences, no wasted words. First sentence states purpose and key behavior (async, job ID), second gives critical usage instruction.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the overall flow but lacks parameter details. Since an output schema exists, return values are covered. However, given the tool has 5 parameters with zero schema description, the description should offer some context on what they do.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, yet the description provides no information about any of the 5 parameters (repo_url, base_ref, head_ref, idempotency_key, output_language). The description adds no value beyond the schema's basic field names.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool starts an asynchronous analysis and returns a job ID. It uses specific verb 'Start' and resource 'architecture-guided release-note analysis', distinguishing it from sibling tools like archlog_check_environment and archlog_validate_request.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly advises to poll with archlog_get_status and not wait, providing clear usage guidance. It does not explicitly state when to use this tool versus alternatives, but the sibling tools are sufficiently different.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

archlog_validate_requestA

Validate and normalize a GitHub C/C++ release range. This performs no checkout and starts no analysis.

ParametersJSON Schema
NameRequiredDescriptionDefault
base_refYes
head_refYes
repo_urlYes
output_languageNozh

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.8/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses that the tool performs no checkout and starts no analysis, which is valuable. However, it does not explain what 'normalize' entails or potential side effects beyond the stated limitations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description consists of two concise sentences with no redundant information. It is efficiently front-loaded with the primary action and then clarifies limitations.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description lacks parameter details and does not explain what validation or normalization means exactly. Although an output schema exists (not shown), the incomplete parameter descriptions reduce overall completeness for a 4-parameter tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It entirely fails to describe any of the four parameters (repo_url, base_ref, head_ref, output_language), leaving the agent without semantic understanding beyond the schema keys.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool validates and normalizes a GitHub C/C++ release range, with a specific verb and resource. It also explicitly states what it does not do (no checkout, no analysis), distinguishing it from sibling tools that likely perform analysis or environment checks.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies this tool is for preliminary validation before analysis, but it lacks explicit guidance on when to use it vs. the sibling tools. No direct contrast or prerequisites are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv0.1.0
    • First observedarchlog_check_environment
    • First observedarchlog_start_analysis
    • First observedarchlog_validate_request
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4/5.0

Scored across 3 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: starting an analysis, checking the environment, and validating a request. There is no overlap or ambiguity.

Naming Consistency5/5

All tool names follow a consistent 'archlog_verb_noun' pattern, making them predictable and easy to understand.

Tool Count5/5

Three tools are appropriate for the server's focused scope of architecture-guided release-note analysis, covering essential steps without being excessive or thin.

Completeness2/5

The set references a 'archlog_get_status' tool for polling, but it is missing from the provided tools. This is a significant gap that would cause agent failures when trying to retrieve analysis results.

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • trazabilidad-mcp

    lucadevv
    F
    license
    Not graded
    quality
    B
    maintenance
    MCP server that exposes code tracing capabilities including journey flows, HTTP seams, and findings from indexed projects, allowing AI assistants to query software architecture.
    -

  • DevForge-MCP

    Sanket2329
    A
    license
    Not graded
    quality
    A
    maintenance
    A production-ready MCP server that enables AI assistants to intelligently understand, analyze, edit, navigate, and review software projects with multi-workspace support, Git integration, and semantic search.
    1
    MIT

  • repos-expert

    end1989
    A
    license
    Not graded
    quality
    A
    maintenance
    MCP server that studies a folder of code repositories, generates markdown documentation (architecture, interfaces, activity), and serves answers over MCP with live ripgrep search and file reads so AI assistants can query codebases and their relationships.
    55 npm
    MIT