Add CP1 Discovery agents in both patterns
All checks were successful
check agents / check (push) Successful in 10s
All checks were successful
check agents / check (push) Successful in 10s
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>
This commit is contained in:
196
mcp-servers/alz-discovery-sample/README.md
Normal file
196
mcp-servers/alz-discovery-sample/README.md
Normal file
@@ -0,0 +1,196 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user