Implement milestone-2 process inspection

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: Copilot Scribe

.squad/decisions/inbox/ripley-plan-m2.md

@@ -0,0 +1,27 @@
+# Ripley Decision: M2 Plan Update
+
+**Date:** Session 792ebf1b  
+**Role:** Lead  
+
+## Decision
+
+Updated project plan to reflect current progress after Milestone 2 implementation and validation.
+
+## Rationale
+
+1. **M1 published** — Feature complete, branch frozen
+2. **Branch model aligned** — Clear separation: master (stable) → milestone-1 (frozen) → milestone-2 (dev)
+3. **M2 process inspection** — Implemented on milestone-2, validation confirmed
+4. **Next phase identified** — Integration testing with client is the logical follow-up
+
+## Changes made
+
+- Updated `plan.md` status section to reflect M1/M2 state
+- Added branch model clarity
+- Documented process inspection completion
+- Identified next work items (integration testing, diagnostics expansion, docs)
+
+## Risk/Notes
+
+- Ensure M2 branch remains stable and tests continue to pass
+- Integration testing will be first opportunity to validate M2 tools with real Azure client calls

README.md

@@ -1,11 +1,11 @@
 # Linux Diagnostics MCP Server - Lecture Demo
 
-A Python/Linux adaptation of the original `MCPDemo` teaching repository. This repo mirrors the C# demo's public structure and documentation style while staying truthful about current scope: **Milestone 1 parity only** today.
+A Python/Linux adaptation of the original `MCPDemo` teaching repository. This repo now reaches **Milestone 2 parity** for the public teaching flow: compact system inspection plus Linux process listing and drill-down.
 
 ## What This Demo Shows
 
 This is an early **MCP lecture demo** with:
-- ✅ **Tools**: one read-only Linux diagnostics tool, `get_system_info`
+- ✅ **Tools**: read-only Linux diagnostics tools for `get_system_info`, `get_process_list`, `get_process_by_id`, and `get_process_by_name`
 - ✅ **AI Chat Client**: a Python Azure OpenAI client that launches the local stdio server and lets the model call MCP tools
 - ✅ **STDIO transport**
 - ✅ **Python 3.12 implementation** with the official MCP Python SDK
@@ -41,7 +41,8 @@ This script:
 2. Performs the MCP handshake
 3. Discovers tools
 4. Executes `get_system_info`
-5. Verifies the lecture chat client fails safely when Azure OpenAI settings are missing
+5. Exercises the process inspection tools
+6. Verifies the lecture chat client fails safely when Azure OpenAI settings are missing
 
 ### 3. Test with MCP Inspector
 
@@ -53,7 +54,7 @@ mcp dev src/mcp_linux_diag_server/server.py:server --with-editable .
 Then in Inspector:
 1. Connect to the server
 2. Open the **Tools** tab
-3. Select **get_system_info**
+3. Select **get_system_info**, **get_process_list**, **get_process_by_id**, or **get_process_by_name**
 4. Call the tool and inspect the JSON response
 
 ### 4. Use the Lecture Chat Client
@@ -103,10 +104,18 @@ python3 -m mcp_linux_diag_server.client --prompt "What is the system information
   - 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
+
 ## Projects
 
 ### `src/mcp_linux_diag_server/server.py`
-The stdio MCP server exposing the Milestone 1 `get_system_info` tool.
+The stdio MCP server exposing the Milestone 2 diagnostics and process inspection tools.
 
 ### `src/mcp_linux_diag_server/client.py`
 The lecture chat client that:
@@ -119,11 +128,11 @@ The lecture chat client that:
 
 | Method | Visual | Interactive | LLM | Best For |
 |--------|--------|-------------|-----|----------|
-| `python3 scripts/smoke_test.py` | ❌ No | ❌ No | ❌ No | quick verification |
+| `python3 scripts/smoke_test.py` | ❌ No | ❌ No | ❌ No | quick verification of Milestone 1 + 2 tools |
 | MCP Inspector | ✅ Yes | ✅ Yes | ❌ No | development, debugging, teaching |
 | `python3 -m mcp_linux_diag_server.client` | ❌ No | ✅ Yes | ✅ Yes | lecture demo flow |
 
-For a parity-focused Milestone 1 checklist, see [M1_VALIDATION_GUIDE.md](M1_VALIDATION_GUIDE.md).
+For the Milestone 1 validation checklist that still underpins the base lecture flow, see [M1_VALIDATION_GUIDE.md](M1_VALIDATION_GUIDE.md).
 
 ## Project Structure
 
@@ -141,10 +150,13 @@ MCPPythonDemo/
 │       ├── client.py
 │       ├── server.py
 │       └── tools/
+│           ├── processes.py
 │           └── system_info.py
 ├── tests/
 │   ├── test_client.py
 │   ├── test_m1_smoke.py
+│   ├── test_m2_smoke.py
+│   ├── test_processes.py
 │   └── test_system_info.py
 ```
 
@@ -157,12 +169,12 @@ MCPPythonDemo/
 ## Milestones
 
 ✅ **Milestone 1** - Minimal diagnostics tool over stdio plus lecture chat client  
-⏳ **Milestone 2** - Process inspection  
+✅ **Milestone 2** - Process inspection  
 ⏳ **Milestone 3** - Resources and prompts  
 ⏳ **Milestone 4** - HTTP transport and security  
 ⏳ **Milestone 5+** - Elicitation, sampling, and roots
 
-This repo does **not** claim feature parity with the later C# milestones yet.
+This repo does **not** claim feature parity with Milestone 3 and beyond yet.
 
 ## License
 

docs/MCPDemoRoadmap.md

@@ -7,7 +7,7 @@ This roadmap mirrors the teaching arc of the original C# `MCPDemo` repository, b
 | Milestone | Original C# Theme | Python/Linux Plan | Status |
 |----------|--------------------|-------------------|--------|
 | 1 | Minimal stdio diagnostics tool | `get_system_info` + lecture chat client | ✅ Complete |
-| 2 | Process inspection | Linux process listing and per-PID detail | ⏳ Planned |
+| 2 | Process inspection | Linux process listing, per-PID detail, and by-name paging | ✅ Complete |
 | 3 | Resources and prompts | Linux snapshot resources + prompts | ⏳ Planned |
 | 4 | HTTP transport and security | Python HTTP MCP transport + auth | ⏳ Planned |
 | 5 | Elicitation | Confirmation flow for risky operations | ⏳ Planned |
@@ -26,14 +26,15 @@ Implemented today:
   - `/proc/meminfo`
 - Python lecture chat client that launches the server and supports Azure OpenAI tool-calling
 
-This is the only milestone currently implemented in this public Python repo.
+Milestone 1 remains the base teaching path and stays fully supported.
 
-## Milestone 2 – Process inspection ⏳
+## Milestone 2 – Process inspection ✅
 
-Planned scope:
-- list running processes
-- inspect one process by PID
-- keep responses small and lecture-friendly
+Implemented scope:
+- list running processes with lightweight summaries
+- inspect one process by PID with Linux `/proc` detail
+- inspect matching processes by name with default paging (`page_size=5`)
+- keep the summary-first, detail-second teaching flow
 
 ## Milestone 3 – Resources and prompts ⏳
 
@@ -68,4 +69,4 @@ Planned scope:
 
 ## Important Parity Note
 
-This repo intentionally follows the **same milestone progression** as the original C# demo, but it does **not** claim feature parity with the later milestones yet. Public documentation should stay aligned with the real Python implementation state.
+This repo intentionally follows the **same milestone progression** as the original C# demo, but it does **not** claim feature parity with Milestone 3 and later yet. Public documentation should stay aligned with the real Python implementation state.

pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "mcp-linux-diag-server"
 version = "0.1.0"
-description = "Milestone 1 Linux diagnostics MCP server plus lecture chat client for the Season of AI teaching arc."
+description = "Milestone 2 Linux diagnostics MCP server plus lecture chat client for the Season of AI teaching arc."
 readme = "README.md"
 license = { file = "LICENSE.txt" }
 requires-python = ">=3.12"

scripts/smoke_test.py

@@ -35,16 +35,56 @@ async def run_server_smoke() -> dict[str, object]:
 
             tools = await session.list_tools()
             tool_names = [tool.name for tool in tools.tools]
-            if "get_system_info" not in tool_names:
-                raise RuntimeError("get_system_info tool was not advertised by the server")
+            expected_tools = {
+                "get_system_info",
+                "get_process_list",
+                "get_process_by_id",
+                "get_process_by_name",
+            }
+            if not expected_tools.issubset(tool_names):
+                missing_tools = sorted(expected_tools - set(tool_names))
+                raise RuntimeError(f"Expected tools were not advertised by the server: {missing_tools}")
+
+            system_result = await session.call_tool("get_system_info", {})
+            if system_result.isError:
+                raise RuntimeError(f"Tool call failed: {system_result.content}")
+
+            process_list_result = await session.call_tool("get_process_list", {})
+            if process_list_result.isError:
+                raise RuntimeError(f"Process list tool failed: {process_list_result.content}")
+
+            process_list = process_list_result.structuredContent
+            if isinstance(process_list, dict) and "result" in process_list:
+                process_list = process_list["result"]
+            if not isinstance(process_list, list) or not process_list:
+                raise RuntimeError("Expected get_process_list to return at least one process")
+
+            process_detail = None
+            process_page = None
+            for process_entry in process_list[:10]:
+                process_id = process_entry["process_id"]
+                process_name = process_entry["process_name"]
+
+                process_detail_result = await session.call_tool("get_process_by_id", {"process_id": process_id})
+                if process_detail_result.isError:
+                    continue
+
+                process_page_result = await session.call_tool("get_process_by_name", {"process_name": process_name})
+                if process_page_result.isError:
+                    continue
+
+                process_detail = process_detail_result.structuredContent
+                process_page = process_page_result.structuredContent
+                break
 
-            result = await session.call_tool("get_system_info", {})
-            if result.isError:
-                raise RuntimeError(f"Tool call failed: {result.content}")
+            if process_detail is None or process_page is None:
+                raise RuntimeError("Unable to complete live process detail smoke calls")
 
             return {
                 "tools": tool_names,
-                "system_info": result.structuredContent,
+                "system_info": system_result.structuredContent,
+                "process_sample": process_detail,
+                "process_page": process_page,
             }
 
 

src/mcp_linux_diag_server/client.py

@@ -22,6 +22,8 @@
     "You are a helpful Linux diagnostics assistant. "
     "You can call MCP tools that inspect the current Linux or WSL machine. "
     "When the user asks about the system, use get_system_info before answering. "
+    "When the user asks about processes, list them first and then use get_process_by_id "
+    "or get_process_by_name for detail. "
     "Keep answers concise, practical, and grounded in tool results."
 )
 AZURE_OPENAI_SCOPE = "https://cognitiveservices.azure.com/.default"

src/mcp_linux_diag_server/server.py

@@ -1,14 +1,26 @@
-"""Milestone 1 MCP server entrypoint."""
+"""Milestone 2 MCP server entrypoint."""
+
+from typing import Annotated
 
 from mcp.server.fastmcp import FastMCP
+from pydantic import Field
 
-from mcp_linux_diag_server.tools.system_info import SystemInfoResult, collect_system_info
+from mcp_linux_diag_server.tools import (
+    BasicProcessInfo,
+    ProcessDetailResult,
+    ProcessQueryResult,
+    SystemInfoResult,
+    collect_system_info,
+    get_process_by_id as collect_process_by_id,
+    get_processes_by_name as collect_processes_by_name,
+    list_processes as collect_process_list,
+)
 
 server = FastMCP(
     name="Linux Diagnostics Demo",
     instructions=(
-        "Milestone 1 teaching server. Exposes one read-only Linux diagnostics tool "
-        "over stdio and keeps the rest of the MCP surface for later milestones."
+        "Milestone 2 teaching server. Start with compact system or process summaries, "
+        "then drill into one Linux process with the detail tools."
     ),
 )
 
@@ -23,6 +35,42 @@ def get_system_info() -> SystemInfoResult:
     return collect_system_info()
 
 
+@server.tool(
+    name="get_process_list",
+    title="Get Process List",
+    description="Return a lightweight Linux process list with process names and PIDs. Use this before requesting detail.",
+)
+def get_process_list() -> list[BasicProcessInfo]:
+    """Return a lightweight Linux process list."""
+    return collect_process_list()
+
+
+@server.tool(
+    name="get_process_by_id",
+    title="Get Process By ID",
+    description="Return detailed Linux process information for one PID.",
+)
+def get_process_by_id(
+    process_id: Annotated[int, Field(description="Linux process ID to inspect.")],
+) -> ProcessDetailResult:
+    """Return detailed Linux process information for one PID."""
+    return collect_process_by_id(process_id)
+
+
+@server.tool(
+    name="get_process_by_name",
+    title="Get Process By Name",
+    description="Return paged detailed Linux process information for a process name. Defaults to page 1 and 5 results per page.",
+)
+def get_process_by_name(
+    process_name: Annotated[str, Field(description="Process name to match, such as python or python3.")],
+    page_number: Annotated[int | None, Field(description="Optional page number. Defaults to 1.")] = None,
+    page_size: Annotated[int | None, Field(description="Optional page size. Defaults to 5.")] = None,
+) -> ProcessQueryResult:
+    """Return paged detailed Linux process information for a process name."""
+    return collect_processes_by_name(process_name, page_number=page_number, page_size=page_size)
+
+
 def main() -> None:
     """Run the MCP server over stdio."""
     server.run(transport="stdio")

src/mcp_linux_diag_server/tools/__init__.py

@@ -1 +1,33 @@
 """Tool implementations for the Linux diagnostics server."""
+
+from .processes import (
+    BasicProcessInfo,
+    ProcessDetailResult,
+    ProcessMemorySnapshot,
+    ProcessQueryResult,
+    get_process_by_id,
+    get_processes_by_name,
+    list_processes,
+)
+from .system_info import SystemInfoResult, collect_system_info
+
+ProcessInfoResult = ProcessDetailResult
+ProcessMemoryUsage = ProcessMemorySnapshot
+get_process_by_name = get_processes_by_name
+get_process_list = list_processes
+
+__all__ = [
+    "BasicProcessInfo",
+    "ProcessDetailResult",
+    "ProcessInfoResult",
+    "ProcessMemorySnapshot",
+    "ProcessMemoryUsage",
+    "ProcessQueryResult",
+    "SystemInfoResult",
+    "collect_system_info",
+    "get_process_by_id",
+    "get_processes_by_name",
+    "get_process_by_name",
+    "list_processes",
+    "get_process_list",
+]