Multi-Agent Database Discovery System using Claude Code

doc/multi_agent_database_discovery.md

@@ -0,0 +1,246 @@
+# Multi-Agent Database Discovery System
+
+## Overview
+
+This document describes a multi-agent database discovery system implemented using Claude Code's autonomous agent capabilities. The system uses 4 specialized subagents that collaborate via the MCP (Model Context Protocol) catalog to perform comprehensive database analysis.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                     Main Agent (Orchestrator)                       │
+│  - Launches 4 specialized subagents in parallel                     │
+│  - Coordinates via MCP catalog                                      │
+│  - Synthesizes final report                                        │
+└────────────────┬────────────────────────────────────────────────────┘
+                 │
+    ┌────────────┼────────────┬────────────┬────────────┐
+    │            │            │            │            │
+    ▼            ▼            ▼            ▼            ▼
+┌────────┐  ┌────────┐  ┌────────┐  ┌────────┐  ┌────────┐
+│Struct. │  │Statist.│  │Semantic│  │Query   │  │  MCP   │
+│ Agent  │  │ Agent  │  │ Agent  │  │ Agent  │  │Catalog │
+└────────┘  └────────┘  └────────┘  └────────┘  └────────┘
+     │            │            │            │            │
+     └────────────┴────────────┴────────────┴────────────┘
+                          │
+                   ▼              ▼
+              ┌─────────┐  ┌─────────────┐
+              │ Database│  │   Catalog   │
+              │ (testdb)│  │ (Shared Mem)│
+              └─────────┘  └─────────────┘
+```
+
+## The Four Discovery Agents
+
+### 1. Structural Agent
+**Mission**: Map tables, relationships, indexes, and constraints
+
+**Responsibilities**:
+- Complete ERD documentation
+- Table schema analysis (columns, types, constraints)
+- Foreign key relationship mapping
+- Index inventory and assessment
+- Architectural pattern identification
+
+**Catalog Entries**: `structural_discovery`
+
+**Key Deliverables**:
+- Entity Relationship Diagram
+- Complete table definitions
+- Index inventory with recommendations
+- Relationship cardinality mapping
+
+### 2. Statistical Agent
+**Mission**: Profile data distributions, patterns, and anomalies
+
+**Responsibilities**:
+- Table row counts and cardinality analysis
+- Data distribution profiling
+- Anomaly detection (duplicates, outliers)
+- Statistical summaries (min/max/avg/stddev)
+- Business metrics calculation
+
+**Catalog Entries**: `statistical_discovery`
+
+**Key Deliverables**:
+- Data quality score
+- Duplicate detection reports
+- Statistical distributions
+- True vs inflated metrics
+
+### 3. Semantic Agent
+**Mission**: Infer business domain and entity types
+
+**Responsibilities**:
+- Business domain identification
+- Entity type classification (master vs transactional)
+- Business rule discovery
+- Entity lifecycle analysis
+- State machine identification
+
+**Catalog Entries**: `semantic_discovery`
+
+**Key Deliverables**:
+- Complete domain model
+- Business rules documentation
+- Entity lifecycle definitions
+- Missing capabilities identification
+
+### 4. Query Agent
+**Mission**: Analyze access patterns and optimization opportunities
+
+**Responsibilities**:
+- Query pattern identification
+- Index usage analysis
+- Performance bottleneck detection
+- N+1 query risk assessment
+- Optimization recommendations
+
+**Catalog Entries**: `query_discovery`
+
+**Key Deliverables**:
+- Access pattern analysis
+- Index recommendations (prioritized)
+- Query optimization strategies
+- EXPLAIN analysis results
+
+## Discovery Process
+
+### Round Structure
+
+Each agent runs 4 rounds of analysis:
+
+#### Round 1: Blind Exploration
+- Initial schema/data analysis
+- First observations cataloged
+- Initial hypotheses formed
+
+#### Round 2: Pattern Recognition
+- Read other agents' findings from catalog
+- Identify patterns and anomalies
+- Form and test hypotheses
+
+#### Round 3: Hypothesis Testing
+- Validate business rules against actual data
+- Cross-reference findings with other agents
+- Confirm or reject hypotheses
+
+#### Round 4: Final Synthesis
+- Compile comprehensive findings
+- Generate actionable recommendations
+- Create final mission summary
+
+### Catalog-Based Collaboration
+
+```python
+# Agent writes findings
+catalog_upsert(
+    kind="structural_discovery",
+    key="table_customers",
+    document="...",
+    tags="structural,table,schema"
+)
+
+# Agent reads other agents' findings
+findings = catalog_list(kind="statistical_discovery")
+```
+
+## Example Discovery Output
+
+### Database: testdb (E-commerce Order Management)
+
+#### True Statistics (After Deduplication)
+| Metric | Current | Actual |
+|--------|---------|--------|
+| Customers | 15 | 5 |
+| Products | 15 | 5 |
+| Orders | 15 | 5 |
+| Order Items | 27 | 9 |
+| Revenue | $10,886.67 | $3,628.85 |
+
+#### Critical Findings
+1. **Data Quality**: 5/100 (Catastrophic) - 67% data triplication
+2. **Missing Index**: orders.order_date (P0 critical)
+3. **Missing Constraints**: No UNIQUE or FK constraints
+4. **Business Domain**: E-commerce order management system
+
+## Launching the Discovery System
+
+```python
+# In Claude Code, launch 4 agents in parallel:
+Task(
+    description="Structural Discovery",
+    prompt=STRUCTURAL_AGENT_PROMPT,
+    subagent_type="general-purpose"
+)
+
+Task(
+    description="Statistical Discovery",
+    prompt=STATISTICAL_AGENT_PROMPT,
+    subagent_type="general-purpose"
+)
+
+Task(
+    description="Semantic Discovery",
+    prompt=SEMANTIC_AGENT_PROMPT,
+    subagent_type="general-purpose"
+)
+
+Task(
+    description="Query Discovery",
+    prompt=QUERY_AGENT_PROMPT,
+    subagent_type="general-purpose"
+)
+```
+
+## MCP Tools Used
+
+The agents use these MCP tools for database analysis:
+
+- `list_schemas` - List all databases
+- `list_tables` - List tables in a schema
+- `describe_table` - Get table schema
+- `sample_rows` - Get sample data from table
+- `column_profile` - Get column statistics
+- `run_sql_readonly` - Execute read-only queries
+- `catalog_upsert` - Store findings in catalog
+- `catalog_list` / `catalog_get` - Retrieve findings from catalog
+
+## Benefits of Multi-Agent Approach
+
+1. **Parallel Execution**: All 4 agents run simultaneously
+2. **Specialized Expertise**: Each agent focuses on its domain
+3. **Cross-Validation**: Agents validate each other's findings
+4. **Comprehensive Coverage**: All aspects of database analyzed
+5. **Knowledge Synthesis**: Final report combines all perspectives
+
+## Output Format
+
+The system produces:
+
+1. **40+ Catalog Entries** - Detailed findings organized by agent
+2. **Comprehensive Report** - Executive summary with:
+   - Structure & Schema (ERD, table definitions)
+   - Business Domain (entity model, business rules)
+   - Key Insights (data quality, performance)
+   - Data Quality Assessment (score, recommendations)
+
+## Future Enhancements
+
+- [ ] Additional specialized agents (Security, Performance, Compliance)
+- [ ] Automated remediation scripts
+- [ ] Continuous monitoring mode
+- [ ] Integration with CI/CD pipelines
+- [ ] Web-based dashboard for findings
+
+## Related Files
+
+- `simple_discovery.py` - Simplified demo of multi-agent pattern
+- `mcp_catalog.db` - Catalog database for storing findings
+
+## References
+
+- Claude Code Task Tool Documentation
+- MCP (Model Context Protocol) Specification
+- ProxySQL MCP Server Implementation

lib/MySQL_Catalog.cpp

@@ -3,6 +3,7 @@
 #include "proxysql.h"
 #include <sstream>
 #include <algorithm>
+#include "../deps/json/json.hpp"
 
 MySQL_Catalog::MySQL_Catalog(const std::string& path)
 	: db(NULL), db_path(path)
@@ -220,31 +221,40 @@ std::string MySQL_Catalog::search(
 		return "[]";
 	}
 
-	// Build JSON result
-	std::ostringstream json;
-	json << "[";
-	bool first = true;
+	// Build JSON result using nlohmann::json
+	nlohmann::json results = nlohmann::json::array();
 
 	if (resultset) {
 		for (std::vector<SQLite3_row*>::iterator it = resultset->rows.begin();
 		     it != resultset->rows.end(); ++it) {
 			SQLite3_row* row = *it;
-			if (!first) json << ",";
-			first = false;
-
-			json << "{"
-			     << "\"kind\":\"" << (row->fields[0] ? row->fields[0] : "") << "\","
-			     << "\"key\":\"" << (row->fields[1] ? row->fields[1] : "") << "\","
-			     << "\"document\":" << (row->fields[2] ? row->fields[2] : "null") << ","
-			     << "\"tags\":\"" << (row->fields[3] ? row->fields[3] : "") << "\","
-			     << "\"links\":\"" << (row->fields[4] ? row->fields[4] : "") << "\""
-			     << "}";
+
+			nlohmann::json entry;
+			entry["kind"] = std::string(row->fields[0] ? row->fields[0] : "");
+			entry["key"] = std::string(row->fields[1] ? row->fields[1] : "");
+
+			// Parse the stored JSON document - nlohmann::json handles escaping
+			const char* doc_str = row->fields[2];
+			if (doc_str) {
+				try {
+					entry["document"] = nlohmann::json::parse(doc_str);
+				} catch (const nlohmann::json::parse_error& e) {
+					// If document is not valid JSON, store as string
+					entry["document"] = std::string(doc_str);
+				}
+			} else {
+				entry["document"] = nullptr;
+			}
+
+			entry["tags"] = std::string(row->fields[3] ? row->fields[3] : "");
+			entry["links"] = std::string(row->fields[4] ? row->fields[4] : "");
+
+			results.push_back(entry);
 		}
 		delete resultset;
 	}
 
-	json << "]";
-	return json.str();
+	return results.dump();
 }
 
 std::string MySQL_Catalog::list(
@@ -282,31 +292,42 @@ std::string MySQL_Catalog::list(
 	resultset = NULL;
 	db->execute_statement(sql.str().c_str(), &error, &cols, &affected, &resultset);
 
-	// Build JSON result with total count
-	std::ostringstream json;
-	json << "{\"total\":" << total << ",\"results\":[";
+	// Build JSON result using nlohmann::json
+	nlohmann::json result;
+	result["total"] = total;
+	nlohmann::json results = nlohmann::json::array();
 
-	bool first = true;
 	if (resultset) {
 		for (std::vector<SQLite3_row*>::iterator it = resultset->rows.begin();
 		     it != resultset->rows.end(); ++it) {
 			SQLite3_row* row = *it;
-			if (!first) json << ",";
-			first = false;
-
-			json << "{"
-			     << "\"kind\":\"" << (row->fields[0] ? row->fields[0] : "") << "\","
-			     << "\"key\":\"" << (row->fields[1] ? row->fields[1] : "") << "\","
-			     << "\"document\":" << (row->fields[2] ? row->fields[2] : "null") << ","
-			     << "\"tags\":\"" << (row->fields[3] ? row->fields[3] : "") << "\","
-			     << "\"links\":\"" << (row->fields[4] ? row->fields[4] : "") << "\""
-			     << "}";
+
+			nlohmann::json entry;
+			entry["kind"] = std::string(row->fields[0] ? row->fields[0] : "");
+			entry["key"] = std::string(row->fields[1] ? row->fields[1] : "");
+
+			// Parse the stored JSON document
+			const char* doc_str = row->fields[2];
+			if (doc_str) {
+				try {
+					entry["document"] = nlohmann::json::parse(doc_str);
+				} catch (const nlohmann::json::parse_error& e) {
+					entry["document"] = std::string(doc_str);
+				}
+			} else {
+				entry["document"] = nullptr;
+			}
+
+			entry["tags"] = std::string(row->fields[3] ? row->fields[3] : "");
+			entry["links"] = std::string(row->fields[4] ? row->fields[4] : "");
+
+			results.push_back(entry);
 		}
 		delete resultset;
 	}
 
-	json << "]}";
-	return json.str();
+	result["results"] = results;
+	return result.dump();
 }
 
 int MySQL_Catalog::merge(

lib/MySQL_Tool_Handler.cpp

@@ -910,7 +910,13 @@ std::string MySQL_Tool_Handler::catalog_get(const std::string& kind, const std::
 	if (rc == 0) {
 		result["kind"] = kind;
 		result["key"] = key;
-		result["document"] = json::parse(document);
+		// Parse as raw JSON value to preserve nested structure
+		try {
+			result["document"] = json::parse(document);
+		} catch (const json::parse_error& e) {
+			// If not valid JSON, store as string
+			result["document"] = document;
+		}
 	} else {
 		result["error"] = "Entry not found";
 	}