Linux Diagnostics MCP Server - Lecture Demo

A Python/Linux adaptation of the original MCPDemo teaching repository. This repo now reaches Milestone 7 parity for the public teaching flow: compact system inspection, Linux process drill-down, log snapshots as resources, workflow prompts, authenticated MCP over HTTP on /mcp, explicit elicitation before process termination, sampling-assisted Linux diagnostics, and allowed-root proc/sys snapshots.

What This Demo Shows

This lecture demo now includes:

• ✅ Tools: Linux diagnostics tools for get_system_info, get_process_list, get_process_by_id, get_process_by_name, and elicitation-gated kill_process
• ✅ Resources: paged syslog://snapshot/... log snapshot resources
• ✅ Prompts: MCP workflow prompts for error analysis, CPU investigation, security review, and health diagnosis
• ✅ HTTP transport: streamable MCP over http://127.0.0.1:5000/mcp
• ✅ API key auth: X-API-Key header or ?apiKey=secure-mcp-key
• ✅ AI Chat Client: a Python Azure OpenAI client that launches the local HTTP server, lets the model call MCP tools, prompts, and resources, and handles local form elicitation in the terminal
• ✅ Python 3.12 implementation with the official MCP Python SDK
• ✅ Multiple testing methods
• ✅ Milestone 5 elicitation for kill_process
• ✅ Milestone 6 sampling-assisted Linux diagnostics
• ✅ Milestone 7 roots for read-only /proc and /sys snapshots

Quick Start

1. Install

Server-only install:

python3 -m pip install --user --break-system-packages -e .

Install the lecture chat client extras:

python3 -m pip install --user --break-system-packages -e '.[llm]'

2. Quick Smoke Test (No LLM)

python3 scripts/smoke_test.py

This script:

1. Starts the local HTTP MCP server
2. Verifies 401 Unauthorized without an API key
3. Performs the MCP initialize handshake on /mcp
4. Confirms mcp-session-id flow works across requests
5. Discovers tools, prompts, and resource templates
6. Exercises the system, process, log snapshot, proc snapshot, and sampling-assisted diagnostics flows
7. Verifies kill_process fails safely when the client does not advertise elicitation support
8. Verifies the lecture chat client fails safely when Azure OpenAI settings are missing

3. Run the Server Manually

python3 -m mcp_linux_diag_server

The server listens on:

• endpoint: http://127.0.0.1:5000/mcp
• demo API key: secure-mcp-key

4. Test with MCP Inspector or VS Code MCP config

Start the server in one terminal, then connect using the HTTP endpoint above.

This repo includes .vscode/mcp.json with the required header:

{
  "servers": {
    "linux-diag-demo": {
      "url": "http://127.0.0.1:5000/mcp",
      "headers": {
        "X-API-Key": "secure-mcp-key"
      }
    }
  }
}

If your inspector accepts a URL directly, this query-string form also works:

http://127.0.0.1:5000/mcp?apiKey=secure-mcp-key

5. Use the Lecture Chat Client

Copy the sample environment file and fill in your local Azure OpenAI settings:

cp .env.example .env.local
$EDITOR .env.local
python3 -m mcp_linux_diag_server.client --prompt "Summarize this machine."

To mirror the original .NET credential flow more closely, set:

MCP_DEMO_AZURE_OPENAI_USE_DEFAULT_CREDENTIAL=true

and omit the API key.

Run interactive chat:

python3 -m mcp_linux_diag_server.client

Or run a single prompt:

python3 -m mcp_linux_diag_server.client --prompt "What is the system information?"

The Tools

System Information

• get_system_info - Returns a compact Linux or WSL system snapshot
  • Host name
  • Current user
  • Linux distribution description
  • Kernel release
  • Architecture
  • Logical CPU count
  • Python runtime
  • Current working directory
  • Uptime
  • Load averages
  • Memory summary
  • WSL detection flag

Process Inspection

• get_process_list - Returns a lightweight list of running processes with names and PIDs
• get_process_by_id - Returns detailed Linux process information for one PID
• get_process_by_name - Returns paged detailed process information for a process name
  • Defaults to page_number=1
  • Defaults to page_size=5
  • Keeps the list-first, detail-second teaching flow from the original demo
• kill_process - Terminates a Linux process only after explicit elicitation
  • If process_id is omitted, the server samples the top CPU consumers and asks the client to choose one
  • The server always requires the typed confirmation phrase CONFIRM PID {pid}
  • The lecture client handles these prompts locally in the terminal when stdin/stdout are interactive
• troubleshoot_linux_diagnostics - Uses sampling to convert a natural-language Linux diagnostics question into a validated /proc or /sys read
  • The server validates the sampled path and field against an allowlist before reading anything
  • Exact Python adaptation: the sampled query is a single safe PATH or PATH | grep FIELD line instead of WQL
  • The server then samples again to summarize the observation back to the user
• create_proc_snapshot - Creates an immutable read-only snapshot from an allowed /proc or /sys path and returns resource URIs
  • File snapshots page line-by-line content
  • Directory snapshots page deterministic child metadata without following symlinks
  • Enforces explicit allowed roots before reading anything
• request_proc_access - Uses elicitation to request read-only access to an additional /proc or /sys root
  • Adds the approved root to the server's in-memory allowlist
  • Lets the model ask for access proactively before a blocked snapshot attempt

Log Snapshots

• create_log_snapshot - Creates an immutable snapshot from a common Linux log file and returns resource URIs
  • Supports system, security, kernel, and package log groups
  • Optional filter_text narrows the snapshot to matching lines
  • Returns a base resource URI plus a paginated resource template

Resources

• syslog://snapshot/{snapshot_id} - Reads a stored Linux log snapshot with default pagination
• syslog://snapshot/{snapshot_id}?limit={limit}&offset={offset} - Reads a specific page from a stored snapshot
• proc://snapshot/{snapshot_id} - Reads a stored proc/sys snapshot with default pagination
• proc://snapshot/{snapshot_id}?limit={limit}&offset={offset} - Reads a specific page from a stored proc/sys snapshot

Every resource read returns:

• snapshot metadata
• captured entries
• pagination metadata (total_count, returned_count, limit, offset, has_more, next_offset)

Prompts

• AnalyzeRecentApplicationErrors - Error-focused log analysis workflow
• ExplainHighCpu - Correlate CPU-heavy processes with Linux logs
• DetectSecurityAnomalies - Review suspicious processes plus auth/security log evidence
• DiagnoseSystemHealth - End-to-end system health workflow
• TroubleshootLinuxComponent - Focused deep-dive workflow that steers the agent toward troubleshoot_linux_diagnostics

Projects

src/mcp_linux_diag_server/server.py

The authenticated HTTP MCP server exposing the Milestone 1-7 diagnostics tools, resources, and workflow prompts.

src/mcp_linux_diag_server/client.py

The lecture chat client that:

• launches the local HTTP server
• connects over streamable HTTP with the demo API key
• exposes MCP prompt/resource APIs as helper tools for the model
• fulfills MCP form elicitation in the local terminal when the model triggers kill_process
• fulfills MCP sampling requests so the server can synthesize safe Linux diagnostics queries and summaries
• teaches the model to request proc/sys access before snapshotting blocked paths
• executes tool-calling turns

Testing Methods

Method	Visual	Interactive	LLM	Best For
python3 scripts/smoke_test.py	❌ No	❌ No	❌ No	quick verification of M1-M7 server behavior
MCP Inspector / .vscode/mcp.json	✅ Yes	✅ Yes	❌ No	development, debugging, teaching
python3 -m mcp_linux_diag_server.client	❌ No	✅ Yes	✅ Yes	lecture demo flow

For the Milestone 1 validation checklist that still underpins the base lecture flow, see M1_VALIDATION_GUIDE.md.

Project Structure

MCPPythonDemo/
├── README.md
├── LICENSE.txt
├── pyproject.toml
├── .env.example
├── .vscode/
│   └── mcp.json
├── scripts/
│   └── smoke_test.py
├── src/
│   └── mcp_linux_diag_server/
│       ├── __main__.py
│       ├── client.py
│       ├── http_config.py
│       ├── server.py
│       └── tools/
│           ├── log_snapshots.py
│           ├── proc_snapshots.py
│           ├── processes.py
│           └── system_info.py
├── tests/
│   ├── http_harness.py
│   ├── test_client.py
│   ├── test_m1_smoke.py
│   ├── test_m2_smoke.py
│   ├── test_m3_smoke.py
│   ├── test_m4_http.py
│   ├── test_log_snapshots.py
│   ├── test_processes.py
│   └── test_system_info.py

Requirements

• Python 3.12+
• mcp[cli]
• Azure OpenAI only if you want to run the lecture chat client

Milestones

✅ Milestone 1 - Minimal diagnostics tool over stdio plus lecture chat client
✅ Milestone 2 - Process inspection
✅ Milestone 3 - Log snapshot resources and prompts
✅ Milestone 4 - HTTP transport and security
✅ Milestone 5 - Elicitation-backed kill_process
✅ Milestone 6 - Sampling-assisted Linux diagnostics
✅ Milestone 7 - Roots and proc/sys snapshots

License

MIT. See LICENSE.txt.

Resources

• Model Context Protocol
• MCP Inspector
• Azure OpenAI
• Original C# MCPDemo