# centralmcp — HPE Networking MCP toolkit

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
[![MCP](https://img.shields.io/badge/MCP-FastMCP-brightgreen)](https://modelcontextprotocol.io/)
[![CI](https://github.com/secure-ssid/centralmcp/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/secure-ssid/centralmcp/actions/workflows/ci.yml)
[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-0969da)](https://secure-ssid.github.io/centralmcp/)
[![Release](https://img.shields.io/github/v/release/secure-ssid/centralmcp?display_name=tag)](https://github.com/secure-ssid/centralmcp/releases)

![centralmcp banner showing 6,144 generated operations, 6,703 backend tools, 3 minimal router tools, and nine platform surfaces with embedded RAG](docs/assets/centralmcp-hero.svg)

The banner tracks the current backend catalog: a large tool surface stays
available on demand, while the MCP client itself only ever sees three router
tools by default.

**Low-token Model Context Protocol (MCP) server for HPE Networking automation: Aruba Central, HPE GreenLake Platform (GLP), ClearPass, Juniper Mist, Apstra, ArubaOS 8 migration automation, EdgeConnect, HPE Aruba UXI, and Axis Atmos Cloud.**

centralmcp gives MCP-capable AI clients a low-token way to search Aruba/HPE
docs, look up exact OpenAPI details, inspect Central health, run
troubleshooting workflows, manage configuration, execute guarded ArubaOS 8
migrations, and use guarded GreenLake Platform operations. It is built around
direct REST calls with `httpx`.

For the full visual walkthrough of this same information — audience picker,
diagrams, and write-safety flow — see the
[centralmcp GitHub Pages site](https://secure-ssid.github.io/centralmcp/).
This README stays intentionally short; canonical guides live under `docs/`.

## Who it's for

| You are... | Start with |
|---|---|
| A first-time MCP user | The [five-minute credential-free quickstart](#five-minute-credential-free-quickstart) below, then [Getting started](docs/getting-started.md) |
| An Aruba network operator | [Example prompts](docs/example-prompts.md) and [typed product workflows](docs/product-workflows.md) |
| A centralmcp developer | [Architecture overview](docs/architecture/system-overview.md) and [Contributing guide](CONTRIBUTING.md) |

## Five-minute credential-free quickstart

Verify the install, build the router catalog, and start the MCP HTTP server
before adding any Aruba Central or GreenLake Platform credentials:

```bash
git clone https://github.com/secure-ssid/centralmcp.git
cd centralmcp
python3 scripts/setup_wizard.py --yes --skip-credentials
uv run python scripts/doctor.py
MCP_PORT=8010 bash scripts/run_http_router.sh
```

Expected outcomes:

- The wizard prints each completed phase and ends with a setup-complete summary; no Central/GLP calls are made.
- `doctor.py` reports local dependency, config-path, and index checks — everything reads `OK` or lists what to fix, without calling any vendor API.
- The HTTP router prints a `Uvicorn running on http://127.0.0.1:8010` line and keeps running in the foreground.

<figure>
  <img src="docs/assets/diagrams/quickstart-journey.svg" alt="Six steps from cloning centralmcp through setup, doctor checks, MCP connection, tool discovery, and a safe read-only call">
</figure>

The same six steps this diagram shows — clone, run the wizard, check the
doctor, connect, discover, and call safely — are exactly what the commands
above walk through.

Connect any MCP-capable client to `http://127.0.0.1:8010/mcp`, then try a
credential-free discovery call:

```text
find_tool("ask Aruba docs with citations")
invoke_read_tool("ask_docs", {"question": "WPA3 SAE transition mode", "top_k": 5})
```

Expected outcome: a short, cited answer from the embedded docs index — this
call only reaches the local RAG index, never Central or GLP.

## Write safety at a glance

- `find_tool` only searches the local tool catalog; it never calls a vendor API.
- `invoke_read_tool` blocks any backend tool that is not annotated read-only.
- `invoke_tool` is deliberately marked destructive because it can also dispatch write/destructive backend tools — use it only when a write is intended.
- Use `dry_run=True` first when supported; real execution then requires either `confirm=True` or MCP elicitation, depending on the tool schema.
- Optional product writes stay blocked by default (`CENTRALMCP_PRODUCT_ACCESS=read-only`); a global or per-platform override is required for lab read-write access.
- Credentials stay in `config/credentials.yaml` or environment variables and are never committed.

See [Tool router](docs/tool-router.md) for the complete discovery/dispatch/write-safety model.

## Project snapshot

| Area | Current snapshot |
|---|---|
| Tool catalog | Non-additive profiles: 363 core tools / 2824 read-only optional starters / 5804 read-write optional starters; complete backend index: 6,703 |
| RAG | 51,737 prose chunks; 244 specs, 3,796 endpoints, 11,293 schemas, 60,568 fields, 102 advisories, 346 lifecycle records |
| Optional platforms | ClearPass, Mist, Apstra, AOS8, EdgeConnect, UXI, Axis Atmos Cloud |
| Safety | Per-platform write gates, dry-run + confirmation, HTTP host/origin and bearer controls, credential-gated live-test config |

Full per-backend counts live in [Tool catalog](docs/tool-catalog.md). See the
[0.7.0 release notes](docs/release-notes-0.7.0.md) for everything added in the
current release, and the [capability gap matrix](docs/capability-gap-matrix.md)
for reproducible tool/benchmark comparisons.

## Why the router matters

Point your MCP client at **one** server: `mcp_servers/tool_router.py`. The
recommended `minimal` profile keeps the client-visible tool list at three
entries while still reaching the full backend catalog:

1. `find_tool` — discover the right backend tool.
2. `invoke_read_tool` — dispatch read-only calls.
3. `invoke_tool` — dispatch intentional write/destructive calls only.

## Task-oriented guides

| Need | Guide |
|---|---|
| Full setup, credentials, and MCP client connection | [Getting started](docs/getting-started.md) |
| Copy/paste stdio or streamable HTTP client config | [MCP client recipes](docs/mcp-client-recipes.md) |
| Router modes, toolsets, and safe dispatch in depth | [Tool router](docs/tool-router.md) |
| Real prompts with expected call shapes | [Example prompts](docs/example-prompts.md) |
| Enable ClearPass, Mist, Apstra, AOS8, EdgeConnect, UXI, or Axis | [Optional product starters](docs/optional-products.md) |
| Typed product-specific workflow roadmap | [Product workflows](docs/product-workflows.md) |
| Fix setup, credential, HTTP, or catalog issues | [Troubleshooting](docs/troubleshooting.md) |
| Architecture, data flow, and safety diagrams | [System overview](docs/architecture/system-overview.md) |
| Every backend's tool counts and coverage | [Tool catalog](docs/tool-catalog.md) |
| The complete task-based visual gateway | [centralmcp GitHub Pages](https://secure-ssid.github.io/centralmcp/) |
| Every documentation page, grouped by purpose | [docs/README.md](docs/README.md) |
| Contribute, get support, or report a security issue | [CONTRIBUTING.md](CONTRIBUTING.md), [SUPPORT.md](SUPPORT.md), [SECURITY.md](SECURITY.md) |

## Local setup essentials

The default MCP client profile stays lean:

```env
CENTRALMCP_ROUTER_MODE=minimal
CENTRALMCP_TOOLSETS=central,glp,rag
```

Enable optional products only when needed:

```env
CENTRALMCP_PRODUCTS=clearpass,mist,apstra,aos8,edgeconnect,uxi,axis,design
CENTRALMCP_PRODUCT_ACCESS=read-only
```

`.claude/launch.json` ships a matching minimal `aruba-tool-router` launch
profile for daily use. `find_tool` omits full JSON schemas by default; request
`include_schema=true` only when a client needs the full parameter shape.

Build or refresh the router tool index, and download the prebuilt RAG/OpenAPI
indexes instead of scraping locally:

```bash
uv run python scripts/ingest_tools.py --products all
uv run python scripts/download_indexes.py
```

See [Getting started](docs/getting-started.md) for credentials, region
selection, optional-product env vars, and the full ingestion/refresh path.

## Streamable HTTP mode

```bash
MCP_PORT=8010 bash scripts/run_http_router.sh
```

Then point any MCP-capable client at `http://127.0.0.1:8010/mcp`. The server
also exposes `/livez`, `/readyz`, and `/healthz`. Non-loopback binds require
explicit `MCP_ALLOWED_HOSTS`/`MCP_ALLOWED_ORIGINS` and can be protected with
`MCP_HTTP_BEARER_TOKEN`. See [MCP client recipes](docs/mcp-client-recipes.md)
for copy/paste stdio and HTTP configs.

## Project layout

```text
mcp_servers/     Low-token router + Central/GLP/RAG/optional-product servers
pipeline/        httpx clients, 8-stage migration pipeline, SSID helpers
ingestion/       Docs/API scraping and LanceDB + SQLite index builders
docs/            Setup, router, architecture, product, and release guides
scripts/         Setup wizard, local doctor, HTTP router helper, release validation
tests/           Unit, integration, and RAG eval coverage
config/          Credentials template; real credentials stay git-ignored
run_pipeline.py  Migration pipeline CLI
run_ssid.py      SSID helper CLI
```

The full repository map, including generated/git-ignored paths, lives in
[System overview](docs/architecture/system-overview.md#repository-map).

## Validation

```bash
uv run pytest tests/unit -q
uv run python scripts/validate_release.py --catalog-products all --strict-rag --strict-tool-index --min-tools 6703
```

The release helper runs unit tests, optional RAG/API eval when indexes exist, tool catalog floor checks, and local tool-index freshness checks. Unit tests also include static guards for the active MCP/pipeline code, committed low-token MCP config examples, local-only config files, router product/toolset docs, bounded generic read-only GET tools, MCP list default bounds, RAG/search top_k bounds, public tool-count claims, tool-count docstrings, tracked Markdown local links and images, Pages sitemap and robots metadata, documented router example arguments, product workflow tool-name tables, and wizard optional-product env tables.

## Related projects and thanks

centralmcp is an independent HPE Networking MCP toolkit, improved by watching
the official MCP ecosystem and community work:

- [HewlettPackard/gl-mcp](https://github.com/HewlettPackard/gl-mcp) - official GreenLake Platform MCP server
- [modelcontextprotocol/python-sdk](https://github.com/modelcontextprotocol/python-sdk) - MCP Python SDK
- [KarthikSKumar98/central-mcp-server](https://github.com/KarthikSKumar98/central-mcp-server) - community Aruba Central MCP server
- [nowireless4u/hpe-networking-mcp](https://github.com/nowireless4u/hpe-networking-mcp) - unified HPE networking MCP reference

## Disclaimer

centralmcp is an independent community project. It is not an official HPE or
HPE Aruba Networking product and is not endorsed by or supported by HPE.

## License

MIT - see the [repository license](LICENSE). Generated API metadata and
upstream implementation references are documented in
[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).