Add FastMCP dev servers + notebook launcher; update sprint artifacts

Author: gitwalter

docs/agile/catalogs/CURRENT_BACKLOG.md

@@ -11,7 +11,7 @@
 
 2. **MCP server suite runbook and canonical configuration**
    - **User Story**: US-MCP-002
-   - **Outcome**: Local FastMCP servers are easy to run; client connectivity is easy to validate
+   - **Outcome**: Development MCP server suite is easy to run; client connectivity is easy to validate
 
 3. **Coordinator + specialist subagent composition**
    - **User Story**: US-DEEPAGENTS-002

docs/agile/catalogs/SPRINT_SUMMARY.md

@@ -17,7 +17,7 @@
 
 | ID | Title | Status | Points |
 |----|-------|--------|--------|
-| US-MCP-002 | FastMCP Tool Server Suite + Client Configuration | Not started | 8 |
+| US-MCP-002 | Development MCP Tool Server Suite + Client Configuration | Not started | 8 |
 | US-DEEPAGENTS-001 | DeepAgents Baseline Agent with MCP Tools + Memory | Not started | 13 |
 | US-DEEPAGENTS-002 | Specialized Subagents + Coordinator Routing | Not started | 8 |
 | US-DEEPAGENTS-003 | HITL + Safety for Sensitive Operations | Not started | 5 |

docs/agile/catalogs/TASK_CATALOG.md

@@ -12,12 +12,14 @@ This catalog provides detailed visibility into all tasks across user stories, in
 
 ## Active Sprint Tasks (Sprint 8)
 
-### US-MCP-002: FastMCP Tool Server Suite + Client Configuration (8 Points)
+### US-MCP-002: Development MCP Tool Server Suite + Client Configuration (8 Points)
 | Task ID | Task Description | Estimate | Status | Owner | Notes |
 |---------|------------------|----------|--------|-------|-------|
-| T-MCP-002-01 | Define canonical local MCP server ports/endpoints and runbook | 2h | To Do | AI Team | Document ports 8000-8003 |
-| T-MCP-002-02 | Add client connectivity check (tool discovery + one tool call per server) | 3h | To Do | AI Team | Keep minimal and reliable |
-| T-MCP-002-03 | Document failure modes (missing env vars, server down, wrong port) | 1h | To Do | AI Team | Focus on actionable errors |
+| T-MCP-002-01 | Define canonical development MCP server suite (ports/endpoints) + runbook | 2h | To Do | AI Team | dev_repo/dev_search/dev_tests/github/dev_docs |
+| T-MCP-002-02 | Add client connectivity check (tool discovery + one safe tool call per server) | 3h | To Do | AI Team | Keep minimal and reliable |
+| T-MCP-002-03 | Document failure modes + safety policy (read-only default; write/exec gated by HITL) | 2h | To Do | AI Team | Align with project safety rules |
+| T-MCP-002-04 | Define allowlist for dev_tests/github (what commands are permitted without approval) | 2h | To Do | AI Team | Default to read-only; keep strict |
+| T-MCP-002-05 | Add research + RAG servers (dev_research/dev_knowledge) and document network policy | 3h | To Do | AI Team | Web + vector DB retrieval via MCP |
 
 ### US-DEEPAGENTS-001: DeepAgents Baseline Agent with MCP Tools + Memory (13 Points)
 | Task ID | Task Description | Estimate | Status | Owner | Notes |
@@ -29,7 +31,7 @@ This catalog provides detailed visibility into all tasks across user stories, in
 ### US-DEEPAGENTS-002: Specialized Subagents + Coordinator Routing (8 Points)
 | Task ID | Task Description | Estimate | Status | Owner | Notes |
 |---------|------------------|----------|--------|-------|-------|
-| T-DA-002-01 | Create 2-3 specialist subagents with MCP tools | 3h | To Do | AI Team | finance/news/weather |
+| T-DA-002-01 | Create 2-3 specialist subagents with MCP tools | 3h | To Do | AI Team | repo/search/tests/git/docs + research |
 | T-DA-002-02 | Create coordinator with delegation tools and synthesis | 3h | To Do | AI Team | Must clearly attribute specialists |
 
 ### US-DEEPAGENTS-003: HITL + Safety for Sensitive Operations (5 Points)

docs/agile/catalogs/USER_STORY_CATALOG.md

@@ -31,12 +31,12 @@ Build a reliable foundation for **DeepAgents-based agents** that use **MCP tools
 
 ### In Progress (Week 1)
 
-#### US-MCP-002: FastMCP Tool Server Suite + Client Configuration (8 points)
+#### US-MCP-002: Development MCP Tool Server Suite + Client Configuration (8 points)
 **Priority**: High  
 **Status**: Not started
 
 **Scope**:
-- Standardize how we run the local FastMCP servers (weather/finance/news/calculator)
+- Define and standardize a **development MCP server suite** (repo inspection, search, tests, git, docs)
 - Provide a single place for MCP server endpoints/ports
 - Add a quick connectivity check and example client usage
 
@@ -134,7 +134,7 @@ For complete sprint information, see:
 - Standard deep agent creation, memory via checkpointer, optional persistent memory patterns
 
 ### 2. MCP tools as the core integration surface
-- Local FastMCP servers (weather/finance/news/calculator)
+- Development MCP server suite (repo/search/tests/git/docs) for agent building
 - Configurable remote MCP servers (optional)
 
 ### 3. Optional multi-agent delegation

docs/agile/sprints/current_sprint.md

@@ -20,7 +20,7 @@
 
 | ID | Title | Points | Priority | Status |
 |----|-------|--------|----------|--------|
-| **US-MCP-002** | FastMCP Tool Server Suite + Client Configuration | 8 | High | Not started |
+| **US-MCP-002** | Development MCP Tool Server Suite + Client Configuration | 8 | High | Not started |
 | **US-DEEPAGENTS-001** | DeepAgents Baseline Agent with MCP Tools + Memory | 13 | Critical | Not started |
 | **US-DEEPAGENTS-002** | Specialized Subagents + Coordinator Routing | 8 | High | Not started |
 | **US-DEEPAGENTS-003** | HITL + Safety for Sensitive Operations | 5 | High | Not started |

docs/agile/sprints/sprint_8/README.md

@@ -9,16 +9,19 @@
 ## Sprint Overview
 
 ### Success Criteria
-- [ ] Local FastMCP servers can be started via a simple runbook and are reachable from a client
+- [ ] Development MCP server suite can be started via a simple runbook and is reachable from a client
 - [ ] Baseline DeepAgent can load MCP tools and successfully call at least 2 tools end-to-end
 - [ ] Coordinator can delegate to specialists and synthesize a unified response
+- [ ] Agent can perform research and retrieval:
+  - web search via MCP (with sources)
+  - RAG retrieval via MCP (with citations/metadata)
 
 ## User Stories
 
 ### Priority 1 - Must Have
 | Story ID | Title | Story Points | Assignee | Status |
 |----------|-------|--------------|----------|--------|
-| US-MCP-002 | FastMCP Tool Server Suite + Client Configuration | 8 | AI Team | Not started |
+| US-MCP-002 | Development MCP Tool Server Suite + Client Configuration | 8 | AI Team | Not started |
 | US-DEEPAGENTS-001 | DeepAgents Baseline Agent with MCP Tools + Memory | 13 | AI Team | Not started |
 
 ### Priority 2 - Should Have
@@ -34,7 +37,7 @@
 ## Sprint Tasks (High-Level)
 
 ### Development Tasks
-- [ ] Define canonical MCP server config (ports, endpoints) and a runbook
+- [ ] Define canonical development MCP server config (ports, endpoints) and a runbook
 - [ ] Implement baseline DeepAgent entrypoint (tools + memory) consistent with notebook patterns
 - [ ] Implement coordinator + delegation tools to call specialist agents
 

docs/agile/sprints/sprint_8/backlog.md

@@ -12,18 +12,20 @@
 ## Story Overview
 
 **As a** user of the agent system  
-**I want** a coordinator agent that can delegate to specialized subagents (finance/news/weather)  
-**So that** tasks can be routed to the best tool set and the final answer is synthesized from specialist outputs
+**I want** a coordinator agent that can delegate to specialized development subagents (repo/search/tests/git/docs)  
+**So that** real development tasks can be routed to the best tool set and the final answer is synthesized from specialist outputs
 
 ## Acceptance Criteria
 
 - [ ] Define at least 2 specialist subagents with limited, domain-specific MCP tools
 - [ ] Define a coordinator agent with delegation tools (one per specialist)
 - [ ] Coordinator synthesizes results into a single response and indicates which specialist handled what
-- [ ] Demonstrate a multi-domain query that triggers at least 2 specialists
+- [ ] Demonstrate a multi-step development query that triggers at least 2 specialists (e.g., search + tests, or search + git diff)
+- [ ] Include a **research specialist** (web + RAG) for “how do I do X?” development questions
 
 ## Notes
 
 - Reference patterns: `tests/deep_agents/deep_agents_mcp.ipynb` (specialized servers + delegation tools)
+- This story depends on the development MCP server suite defined in US-MCP-002.
 
 

docs/agile/sprints/sprint_8/user_stories/US-DEEPAGENTS-002.md

@@ -1,4 +1,4 @@
-# User Story: US-MCP-002 - FastMCP Tool Server Suite + Client Configuration
+# User Story: US-MCP-002 - Development MCP Tool Server Suite + Client Configuration
 
 **Epic**: EPIC-2: Software Development Agents  
 **Sprint**: Sprint 8  
@@ -11,20 +11,78 @@
 ## Story Overview
 
 **As a** developer building agents with MCP tools  
-**I want** a clear, repeatable way to run local FastMCP servers and connect to them from a client  
-**So that** DeepAgents-based agents can reliably discover and call MCP tools during development and demos
+**I want** a clear, repeatable way to run development-focused MCP servers and connect to them from a client  
+**So that** DeepAgents-based agents can reliably discover and call the tools needed for real software development workflows (repo inspection, search, tests, git, docs)
 
 ## Acceptance Criteria
 
-- [ ] Define and document canonical local MCP server ports/endpoints for:
-  - weather (8000), finance (8001), news (8002), calculator (8003)
-- [ ] Provide a runbook for starting all servers locally (separate terminals)
-- [ ] Provide a simple client-side connectivity check (tool discovery and one tool call per server)
-- [ ] Failure modes documented (server down, wrong port, missing env var such as NEWS_API_KEY)
+- [ ] Define and document canonical local MCP server ports/endpoints for a **development server suite**:
+  - **dev_repo** (repo inspection: list/read) on **8100**
+  - **dev_search** (code search: grep/semantic-ish search) on **8101**
+  - **dev_tests** (test runner: pytest/targeted commands, allowlisted) on **8102**
+  - **github** (official GitHub MCP server; remote; uses `GITHUB_TOKEN`) on **(remote)**
+  - **dev_docs** (link scan/validate + docs navigation helpers) on **8104**
+  - **dev_research** (internet research: web search + source capture) on **8105**
+  - **dev_knowledge** (RAG retrieval + knowledge base maintenance) on **8106**
+- [ ] Provide a runbook for starting the suite locally (separate terminals) and verifying the ports are reachable
+- [ ] Provide a minimal client-side connectivity check:
+  - tool discovery per server
+  - one safe read-only tool call per server (happy path)
+- [ ] Document failure modes and mitigations:
+  - server down / wrong port
+  - missing optional dependencies (pytest, git)
+  - missing env vars for optional integrations
+  - permission errors (workspace path not accessible)
+- [ ] Define a safety policy for development MCP tools:
+  - **Default read-only**
+  - **Any write/exec/git-push requires HITL approval** (handled by US-DEEPAGENTS-003)
+
+## Proposed Tool Map (v1)
+
+These tool IDs are the *capabilities* we want available to the DeepAgent. Implementation can reuse existing tool functions where they already exist (see Notes).
+
+- **dev_repo** (read-only)
+  - `file.list_directory`
+  - `file.read`
+  - `file.search_content`
+  - `file.get_info`
+  - `file.exists`
+- **dev_docs** (read-only by default; healing is gated)
+  - `link.scan_all`
+  - `link.validate`
+  - `link.generate_report`
+  - `link.heal` (RESTRICTED; requires HITL approval)
+- **dev_search** (read-only)
+  - `file.search_content` (baseline)
+  - (future) fast code search across the repo with file-type filters
+- **dev_tests** (execution; allowlisted commands only; can be HITL-gated)
+  - run `pytest` for a specific path/test id
+  - parse failures into a structured summary
+- **github** (remote; read-only by default; any write ops are gated)
+  - Use the official GitHub MCP server at `https://api.githubcopilot.com/mcp/`
+  - Auth: `Authorization: Bearer $GITHUB_TOKEN`
+  - Prefer read-only operations for v1 (search, read, list); gate write operations via HITL
+- **dev_research** (network access; read-only)
+  - `research.plan_research` (query decomposition)
+  - `research.quick_search` (fast web research)
+  - `research.web_search` (full research swarm with verification/synthesis)
+  - `research.get_stats` (capabilities + diagnostics)
+- **dev_knowledge** (RAG + knowledge base)
+  - `rag_swarm.query` (end-to-end: retrieval + response + metrics)
+  - `rag_swarm.semantic_search` (retrieval only)
+  - `rag_swarm.analyze_query` (query analysis/rewrites)
+  - `rag_swarm.get_stats` (capabilities + diagnostics)
+  - (future) software catalog / anti-duplication:
+    - `software_catalog.build_comprehensive_catalog`
+    - `software_catalog.search_catalog_semantic`
 
 ## Notes
 
 - Reference implementation patterns: `tests/deep_agents/deep_agents_mcp.ipynb`
-- Local server code lives in: `utils/mcp/fastmcp/`
+- Existing FastMCP demo servers live in: `utils/mcp/fastmcp/` (weather/finance/news/calculator). Keep them for demos, but Sprint 8 focuses on development tooling.
+- Existing internal MCP tool registry exists under `utils/mcp/server.py` and `utils/mcp/tools/`; we should reuse tool implementations where possible instead of re-inventing them.
+- Existing MCP research and RAG tools already exist:
+  - `utils/mcp/tools/research_swarm_tools.py` (web research swarm)
+  - `utils/mcp/tools/rag_swarm_tools.py` (RAG swarm over ContextEngine/Qdrant)