归档检查与提取MCP服务器

archive-mcp

archive-mcp is a Go Model Context Protocol (MCP) server over stdio that inspects and selectively extracts archives using system tools on PATH (no shell).

Documentation

Start here — guides and contracts live under docs/:

Repository meta:

On GitHub, relative links above resolve to the browsable files for the branch/tag you are viewing.

Contents

• What it does
• Supported archive shapes
• External binaries (PATH)
• Stdio JSON contract
• Safety guarantees
• Quickstart
• Configuration
• Sample list_archive_contents

What it does

Details: Tools reference · Examples: Usage.

Supported archive shapes

Extensions / detection (see internal/archive):

• .tar → tar
• .tar.gz, .tgz → targz
• .gz → single-stream gz (not a multi-file container)
• .zip → zip

External binaries (PATH)

Clients should expect binary_missing if required tools are absent — see Troubleshooting.

Stdio transport

One JSON object per line on stdin (NDJSON). stdout carries only JSON; stderr is for logs (--debug adds detail).

MCP hosts (Cursor, Claude Desktop, …)

Use JSON-RPC 2.0 messages (jsonrpc, id, method, params):

• initialize → capabilities + serverInfo
• notifications/initialized → no stdout line (notification)
• tools/list → tool names, descriptions, inputSchema
• tools/call with name + arguments → content / isError (see Usage)

Legacy / scripts

A single-line object with tool (and optional id, params) still works for ad-hoc pipes and tests.

Malformed input

Non-JSON or bad frames: legacy-shaped lines get one invalid_request response and the process exits. JSON-RPC lines return a JSON-RPC error when possible — see Troubleshooting and Client contract.

Safety guarantees

• No shell interpolation (exec.CommandContext only).
• Bounded command timeouts and stdout/stderr capture limits.
• Path traversal prevention and archive entry validation.
• Extraction: no overwrite, optional allowed output base, symlink/hardlink entries refused by default.

More detail: SECURITY.md · Errors: Client contract.

Quickstart

go build -o bin/archive-mcp ./cmd/archive-mcp
./bin/archive-mcp

Embedded version string (shown in ping):

go build -ldflags "-X main.buildVersion=$(git describe --tags --always)" -o bin/archive-mcp ./cmd/archive-mcp

Ping:

{"id":"req-1","tool":"ping"}

{"id":"req-1","result":{"ok":true,"version":"dev","server":"archive-mcp"}}

Configuration

Flags and equivalent environment variables (see internal/config):

Example:

./bin/archive-mcp --timeout 10 --max-output-bytes 1048576 --debug

Limits also appear in Client contract.

Sample list_archive_contents

{
  "id": "req-list-1",
  "tool": "list_archive_contents",
  "params": {
    "archive_path": "internal/archive/testdata/sample.tar",
    "max_entries": 100,
    "include_details": true
  }
}

License

Licensed under Apache-2.0. See LICENSE.