Metadata-Version: 2.4
Name: axm-mcp
Version: 0.4.1
Summary: AXM MCP Server — Runtime execution for the axm-protocols ecosystem
Project-URL: Homepage, https://github.com/axm-protocols/axm-forge
Project-URL: Documentation, https://axm-protocols.github.io/axm-mcp/
Project-URL: Repository, https://github.com/axm-protocols/axm-forge.git
Project-URL: Issues, https://github.com/axm-protocols/axm-forge/issues
Author-email: Gabriel Jarry <gabriel@axm-protocols.io>
License: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: axm
Requires-Dist: cyclopts>=4.5.1
Requires-Dist: httpx>=0.28
Requires-Dist: mcp[cli]>=1.25.0
Requires-Dist: starlette>=1.2
Provides-Extra: all
Requires-Dist: axm-ast; extra == 'all'
Requires-Dist: axm-audit; extra == 'all'
Requires-Dist: axm-bib; extra == 'all'
Requires-Dist: axm-git; extra == 'all'
Requires-Dist: axm-init; extra == 'all'
Requires-Dist: axm-ticket; extra == 'all'
Provides-Extra: ast
Requires-Dist: axm-ast; extra == 'ast'
Provides-Extra: audit
Requires-Dist: axm-audit; extra == 'audit'
Provides-Extra: bib
Requires-Dist: axm-bib; extra == 'bib'
Provides-Extra: forge
Requires-Dist: axm-ast; extra == 'forge'
Requires-Dist: axm-audit; extra == 'forge'
Requires-Dist: axm-init; extra == 'forge'
Provides-Extra: git
Requires-Dist: axm-git; extra == 'git'
Provides-Extra: init
Requires-Dist: axm-init; extra == 'init'
Provides-Extra: ticker
Requires-Dist: axm-ticket; extra == 'ticker'
Provides-Extra: web
Requires-Dist: scrapling; extra == 'web'
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://raw.githubusercontent.com/axm-protocols/axm-forge/main/assets/logo.png" alt="AXM Logo" width="180" />
</p>

<p align="center">
  <strong>axm-mcp — MCP server for the axm-protocols ecosystem</strong>
</p>

<p align="center">
  <a href="https://github.com/axm-protocols/axm-forge/actions/workflows/ci.yml"><img src="https://github.com/axm-protocols/axm-forge/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://forge.axm-protocols.io/audit/"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/axm-protocols/axm-forge/gh-pages/badges/axm-mcp/axm-audit.json" alt="axm-audit"></a>
  <a href="https://github.com/axm-protocols/axm-forge/actions/workflows/axm-quality.yml"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/axm-protocols/axm-forge/gh-pages/badges/axm-mcp/coverage.json" alt="Coverage"></a>
  <a href="https://pypi.org/project/axm-mcp/"><img src="https://img.shields.io/pypi/v/axm-mcp" alt="PyPI"></a>
  <img src="https://img.shields.io/badge/python-3.12%2B-blue" alt="Python 3.12+">
  <a href="https://forge.axm-protocols.io/"><img src="https://img.shields.io/badge/docs-live-brightgreen" alt="Docs"></a>
</p>

---

## Features

- 🔌 **Auto-discovery** — Finds all `axm.tools` entry points from installed packages
- 🛠️ **MCP bridge** — Exposes discovered tools as Model Context Protocol callables
- ✅ **Verify** — One-shot project quality check: audit + init check + AST enrichment
- 🌐 **Web fetch** — Anti-bot web page fetching via Scrapling (basic / dynamic / stealth)
- 📋 **List tools** — Built-in meta-tool to list all available tools and descriptions
- 📂 **Tool catalog resource** — `axm://tools` MCP resource for passive tool discovery

## Installation

Connect the server to your MCP client (Claude Code, IDE…) in one command — no
manual install, `uvx` fetches the latest version on demand:

```bash
claude mcp add axm-mcp -- uvx --python 3.12 --from "axm-mcp[all]" axm-mcp
```

Prefer editing `.mcp.json` by hand? Add:

```json
{
  "mcpServers": {
    "axm-mcp": {
      "command": "uvx",
      "args": ["--python", "3.12", "--from", "axm-mcp[all]", "axm-mcp"]
    }
  }
}
```

The `[all]` extra is what pulls in the actual tools (`audit`, `ast_*`,
`git_commit`, …); the bare `axm-mcp` package is only the server shell. See the
**[Quick Start](https://forge.axm-protocols.io/mcp/tutorials/quickstart/)** for
the full walkthrough and why each flag matters.

## Server Modes

axm-mcp supports two transport modes. **stdio** (above) is the simple default —
one server process per conversation, works everywhere. **HTTP** is an advanced
option for running a single shared persistent server.

| Mode | Command | Client config | Use case |
|---|---|---|---|
| **stdio** (default) | `axm-mcp` | `uvx --from "axm-mcp[all]" axm-mcp` | Simple, one process per conversation |
| **HTTP** (advanced) | `axm-mcp serve` | `{"type": "url", "url": "http://localhost:9427/mcp"}` | Single shared server, persistent cache |

For the HTTP setup, see [Migrate to HTTP Transport](https://forge.axm-protocols.io/mcp/howto/migration-http/).

## CLI Commands

| Command | Description |
|---|---|
| `axm-mcp` | Start in **stdio** mode (backward-compatible default) |
| `axm-mcp serve [--host HOST] [--port PORT]` | Start Streamable HTTP server (default port `9427`) |
| `axm-mcp status [--host HOST] [--port PORT]` | Check whether the HTTP server is running |
| `axm-mcp stop` | Send SIGTERM to the running HTTP server. Verifies the PID file's process is really `axm-mcp` (via `ps` cmdline) before signalling; if the PID was reused by another process, it refuses to kill it and cleans up the stale PID file |
| `axm-mcp install [--port PORT] [--binary PATH]` | Install axm-mcp as a launchd service (macOS) |
| `axm-mcp uninstall` | Remove the launchd service |

The HTTP transport exposes a `/health` endpoint returning `{"status": "ok", "tools_count": N}`.
Port can also be set via the `AXM_MCP_PORT` environment variable.

## Service Management (macOS)

`axm-mcp` can run as a persistent background service managed by launchd:

```bash
# Install and start the service
axm-mcp install

# Remove the service
axm-mcp uninstall
```

`install` locates the `axm-mcp` binary, generates a launchd plist, and loads it via `launchctl`.
`uninstall` unloads the service and removes the plist file.

## MCP Tools

| Tool | Package | Description |
|---|---|---|
| `list_tools` | built-in | List all available tools |
| `verify` | built-in | One-shot audit + init check + AST enrichment |
| `web_fetch` | built-in | Fetch web pages with anti-bot bypass (basic / dynamic / stealth) |
| `axm://tools` | built-in | MCP resource — passive tool catalog (via `read_resource`) |
| `audit` | `axm-audit` | Code quality audit (lint, types, complexity, security) |
| `init_check` | `axm-init` | 39 governance checks against AXM gold standard |
| `init_scaffold` | `axm-init` | Scaffold a new Python project |
| `bib_search` | `axm-bib` | Search academic papers by title |
| `bib_doi` | `axm-bib` | Resolve DOI → BibTeX |
| `bib_pdf` | `axm-bib` | Download paper PDF |
| `bib_extract` | `axm-bib` | Extract text from PDF |

## Development

This package is part of the **axm-forge** workspace.

```bash
git clone https://github.com/axm-protocols/axm-forge.git
cd axm-forge
uv sync --all-groups
uv run --package axm-mcp --directory packages/axm-mcp pytest -x -q
```

## License

Apache-2.0 — © 2026 Gabriel Jarry
