Files
Jonathan Boniface 416c66ced4
All checks were successful
check agents / check (push) Successful in 10s
Add CP1 Discovery agents in both patterns
ALZ-F01 Discovery as a sub-agent orchestrator (sub-agents/) and as eight
individual declarative agents (individual-agents/), with their KAB workflow
exports. Shared check, render and import scripts, the alz-discovery-sample
MCP server, the crucible-kab-dev deploy profile, deployment docs, platform
issue reports and the source material. Agent steps time out at 20 minutes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-29 18:25:57 +00:00

197 lines
7.7 KiB
Markdown

# ALZ Discovery Sample
Read-only sample data for Agentic Landing Zone discovery (Meridian Retail Group) - scope, estate scans, CMDB and ITSM, inventory, schemas, dependencies, network and the run's MCP call log.
**Version:** 0.1.0
**Server ID:** alz-discovery-sample
**Port:** 8110
---
## 🚀 Quick Start
### As a container (recommended)
The Dockerfile builds the server's image. Run it on the same network as the
MCP Gateway, so the Gateway can reach it by its container name:
```bash
cp .env.example .env # then set MCP_REGISTRATION_API_KEY
podman build -t <image-name> .
podman run -d --name <container-name> --env-file .env --network <gateway-network> <image-name>
```
Register it with the MCP Gateway at `http://<container-name>:8110`.
### Local Development
```bash
# Install dependencies
pip install -r requirements.txt
# Set environment variables
cp .env.example .env
# Edit .env with your configuration
# Run the server
python server.py
```
---
## 📡 API Endpoints
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/health` | GET | Health check (no auth) |
| `/.well-known/mcp-auth` | GET | Authentication requirements |
| `/messages` | POST | MCP JSON-RPC 2.0 endpoint |
---
## 🔧 Available Tools
- **get_scope**: Return the engagement's scope entries, projected to scope_entry_id, hostname, role and site (never notes).
- **list_sources**: List the engagement's registered data sources (connectors) and the tool that serves each.
- **get_budgets**: Return the run's scan-rate, token and tool-call budgets.
- **scan_target**: Return one scope entry's metadata (agentless, metadata level). Only a scope_entry_id is accepted.
- **get_resource_metadata**: Read-only provider metadata for one in-scope cloud resource. The sample estate has no cloud resources.
- **ingest_cmdb**: Pull configuration items through a registered CMDB connector (read-only).
- **ingest_itsm**: Pull incidents and changes (last 12 months) through a registered ITSM connector (read-only).
- **cmdb_query**: Find candidate CIs for one canonical inventory record, matched by serial, FQDN or hostname.
- **diff_records**: Compare one canonical record with one CI attribute by attribute (os, environment, owner, business_service, site, status).
- **list_apps**: List the assets and applications known to the engagement across the loaded sources.
- **get_app**: Return all source records for one application - its scope entries' scan metadata and CMDB CIs.
- **scan_schema**: Return table and column metadata (names, types, comments) for one data store. Never returns row data.
- **get_dependencies**: Return the declared and CMDB relationships for one scope entry.
- **trace_calls**: Return observed calls and flows (metadata only) involving one scope entry, and connection strings found in configuration.
- **trace**: Correlate relationships, configuration and flows into candidate dependency edges for a set of scope entries.
- **collect_topology**: Read devices, links, routed ranges and IPAM for one in-scope site (read-only).
- **map_flows**: Aggregate flow-log metadata into a source-destination-port matrix for one site. Metadata only, never payloads.
- **analyze_bottlenecks**: Return p95 utilisation, latency and loss per link for one site over a window.
- **get_call_log**: Return this server's MCP call log - tool, argument hash, outcome and evidence_ref of every call - for the critic.
- **get_guard_hits**: Return the injection-guard hits recorded on tool results - scope entries whose fields carry instructions aimed at an agent.
---
## 🔐 Authentication
This server uses Bearer token authentication for MCP protocol messages.
```bash
# Test with authentication
curl -X POST http://localhost:8110/messages \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $MCP_REGISTRATION_API_KEY" \
-d '{"jsonrpc": "2.0", "id": "1", "method": "tools/list", "params": {}}'
```
---
## 📋 MCP Gateway Registration
To register this server with the MCP Gateway:
1. Start the server (see Quick Start) where the MCP Gateway can reach it
2. In the MCP Gateway Hub, go to **MCP Servers** → **Add MCP Server**
3. Enter the server details:
- **URL**: Use the **container name** as the hostname (e.g., `http://weather-mcp-server:8110`)
- **API Key**: The `MCP_REGISTRATION_API_KEY` from your `.env` file
4. Click the connection test icon to verify connectivity
5. Enable the server
> **Note:** The URL is the one the MCP Gateway uses, so for a container on the Gateway's network use its container name, not `localhost`.
---
## 🔑 Credentials
This server declares no connection fields, so it holds no credentials for an upstream system. If a tool needs to reach a system with a credential, add connection fields in the MCP Server Builder: each tenant then supplies its own, kept in the Vault Service, instead of one credential in this server's environment.
---
## ✅ Check it before you push
`tests/test_conformance.py` checks the running server against what the MCP Gateway expects: it
refuses callers without its key, answers JSON-RPC correctly, and, if it declares credential fields,
takes the account from each request, refuses a call that carries none, names a missing field, and
never repeats a credential in a reply. It needs only `pytest` and `httpx` and imports nothing from
the server.
```bash
pip install pytest httpx
# with the server running (see Quick Start) and its key from .env
MCP_SERVER_URL=http://localhost:8110 MCP_REGISTRATION_API_KEY=<the key> pytest tests/ -v
```
A check that fails says what to fix. Run it again after you implement your tools, since a tool that
reads an environment variable for its credential, or repeats one in an error, fails it. Checks that
do not apply (a server with no credential fields) are skipped, not passed. To run it with
`REQUIRE_VAULT_CONNECTION=false` on your own machine, set `CONFORMANCE_EXPECT_FAIL_CLOSED=false`.
---
## 🚢 Deploying through the tools repository
To have CI build and deploy this server, put this folder in the root of the
`modernization-tools-mcp-servers` repository as `alz-discovery-sample/`, then add it to
`mcp_servers_to_deploy.yaml` in that repository with the instances it should
run on:
```yaml
- name: "alz-discovery-sample"
instances:
- az_dev
```
The pipeline reads `kubernetes/configmap.yaml` for the server's name and port
(`MCP_SERVER_NAME`, `SERVER_PORT`), generates the registration key and sets it
in the pod, and registers the server with the MCP Gateway.
---
## 📝 Logging
Every line the server writes to stdout is one JSON object (`timestamp`, `level`,
`event`, `logger`, `server_id`, and for a request `request_id`, `method`, `tool`),
including uvicorn's and your tools' own. Each request ends with one
`mcp_request_completed` line carrying `outcome`, `duration_ms` and `error_code`.
- `LOG_LEVEL` sets the level (default `INFO`).
- `LOG_FORMAT=console` prints readable lines instead, for local work.
- In your tool code use the module's `logger`: `logger.info("fetched_issue", key=issue_key)`.
- Do not log credentials, tokens or Authorization headers.
---
## 🛠️ Development
### Implementing Tools
Open `server.py` and find the tool implementation functions. Each tool has a placeholder that needs to be implemented:
```python
async def your_tool_name(arguments: Dict[str, Any]) -> Dict[str, Any]:
# TODO: Implement this tool
raise NotImplementedError("Tool 'your_tool_name' needs implementation")
```
### Testing
```bash
# Health check
curl http://localhost:8110/health
# List tools
curl -X POST http://localhost:8110/messages \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $MCP_REGISTRATION_API_KEY" \
-d '{"jsonrpc": "2.0", "id": "1", "method": "tools/list", "params": {}}'
```
---
## 📄 License
Generated by Agent Builder Platform - Kyndryl (template 1.0.0)