mcp-sequential-research 1.0.0

package/docs/TOOL_CONTRACTS.md

@@ -0,0 +1,431 @@
+# Tool Contracts
+
+This document provides JSON examples for testing both tools without Claude. Use these for regression testing and schema validation.
+
+## Table of Contents
+
+- [sequential_research_plan](#sequential_research_plan)
+- [sequential_research_compile](#sequential_research_compile)
+- [raw_results Schema](#raw_results-schema)
+- [Minimum Viable Test Data](#minimum-viable-test-data)
+
+---
+
+## sequential_research_plan
+
+### Input Schema
+
+```json
+{
+  "topic": "string (required)",
+  "depth": "shallow | standard | deep (default: standard)",
+  "focus_areas": ["string array (optional)"],
+  "constraints": ["string array (optional)"],
+  "output_format": "markdown | json | structured (default: markdown)"
+}
+```
+
+### Example Input
+
+```json
+{
+  "topic": "photonic neural network accelerators",
+  "depth": "standard",
+  "focus_areas": ["silicon photonics", "energy efficiency"],
+  "constraints": ["patent-focused", "post-2020"]
+}
+```
+
+### Example Output
+
+```json
+{
+  "plan_id": "plan-m1abc2def-x9y8z7",
+  "topic": "photonic neural network accelerators",
+  "created_at": "2025-01-13T10:30:00.000Z",
+  "summary": "Research plan for \"photonic neural network accelerators\" with 7 queries at standard depth. Focus areas: silicon photonics, energy efficiency. Execution in 3 phases.",
+  "queries": [
+    {
+      "query_id": "q1",
+      "query_text": "What is photonic neural network accelerators",
+      "query_type": "definition",
+      "extraction_goals": [
+        "Primary definition",
+        "Key characteristics",
+        "Common examples",
+        "Related terminology"
+      ],
+      "priority": "critical"
+    },
+    {
+      "query_id": "q2",
+      "query_text": "Current state of photonic neural network accelerators",
+      "query_type": "current_state",
+      "extraction_goals": [
+        "Current status",
+        "Recent developments",
+        "Key players or stakeholders",
+        "Trends"
+      ],
+      "priority": "critical",
+      "depends_on": ["q1"]
+    },
+    {
+      "query_id": "q3",
+      "query_text": "Compare photonic neural network accelerators",
+      "query_type": "comparison",
+      "extraction_goals": [
+        "Key similarities",
+        "Key differences",
+        "Trade-offs",
+        "Use case recommendations"
+      ],
+      "priority": "medium",
+      "depends_on": ["q1"]
+    },
+    {
+      "query_id": "q4",
+      "query_text": "photonic neural network accelerators: silicon photonics",
+      "query_type": "current_state",
+      "extraction_goals": [
+        "Current state of silicon photonics",
+        "Key developments in silicon photonics",
+        "Challenges and opportunities"
+      ],
+      "priority": "high",
+      "depends_on": ["q1"]
+    },
+    {
+      "query_id": "q5",
+      "query_text": "photonic neural network accelerators: energy efficiency",
+      "query_type": "current_state",
+      "extraction_goals": [
+        "Current state of energy efficiency",
+        "Key developments in energy efficiency",
+        "Challenges and opportunities"
+      ],
+      "priority": "high",
+      "depends_on": ["q1"]
+    }
+  ],
+  "result_schemas": [
+    {
+      "query_id": "q1",
+      "required_fields": [
+        {"field_name": "definition", "field_type": "string", "description": "Core definition", "required": true},
+        {"field_name": "characteristics", "field_type": "array", "description": "Key characteristics", "required": true},
+        {"field_name": "examples", "field_type": "array", "description": "Illustrative examples", "required": true}
+      ],
+      "example": {
+        "definition": "Example value",
+        "characteristics": ["example1", "example2"],
+        "examples": ["example1", "example2"]
+      }
+    }
+  ],
+  "execution_order": [
+    ["q1"],
+    ["q2", "q3", "q4", "q5"]
+  ],
+  "estimated_sources": 15,
+  "metadata": {
+    "depth": "standard",
+    "focus_areas": ["silicon photonics", "energy efficiency"],
+    "constraints": ["patent-focused", "post-2020"],
+    "output_format": "markdown"
+  }
+}
+```
+
+---
+
+## sequential_research_compile
+
+### Input Schema
+
+```json
+{
+  "plan": "PlanOutput object (required)",
+  "raw_results": "RawResult[] (required)",
+  "include_sources": "boolean (default: true)",
+  "include_methodology": "boolean (default: false)",
+  "citation_style": "inline | footnote | endnote (default: inline)"
+}
+```
+
+### Example Input
+
+See [Minimum Viable Test Data](#minimum-viable-test-data) below for a complete example.
+
+### Example Output
+
+```json
+{
+  "report_id": "report-n2bcd3efg-a1b2c3",
+  "plan_id": "plan-m1abc2def-x9y8z7",
+  "title": "Research Report: photonic neural network accelerators",
+  "compiled_at": "2025-01-13T10:35:00.000Z",
+  "executive_summary": "This report presents research findings on **photonic neural network accelerators**. The analysis covers 5 research queries across 4 sections. Key topics include: Overview, Current State, Comparison, Types and Categories.",
+  "sections": [
+    {
+      "heading": "Overview",
+      "level": 2,
+      "content": "Photonic neural network accelerators use optical signals... [1]\n\n**Key Characteristics:**\n- Low latency\n- High bandwidth\n- Energy efficient",
+      "citations_used": ["[1]"]
+    }
+  ],
+  "markdown_report": "# Research Report: photonic neural network accelerators\n\n## Executive Summary\n\nThis report presents research findings...\n\n## Overview\n\nPhotonic neural network accelerators use optical signals... [1]\n\n---\n\n### References\n\n- **[1]**: US Patent 11,123,456 <https://patents.google.com/patent/US11123456>",
+  "sources": [
+    {
+      "id": "[1]",
+      "source_type": "document",
+      "title": "US Patent 11,123,456",
+      "url": "https://patents.google.com/patent/US11123456"
+    }
+  ],
+  "statistics": {
+    "queries_executed": 5,
+    "queries_succeeded": 5,
+    "queries_failed": 0,
+    "total_sources": 6,
+    "word_count": 450
+  }
+}
+```
+
+---
+
+## raw_results Schema
+
+Each element in the `raw_results` array must conform to this schema:
+
+```typescript
+interface RawResult {
+  // Required
+  query_id: string;           // Must match a query_id from the plan
+  success: boolean;           // Whether execution succeeded
+
+  // Optional (required if success=true)
+  data?: {
+    [key: string]: unknown;   // Must match the result_schema for this query
+  };
+
+  // Optional
+  sources?: Citation[];       // Sources consulted
+  error?: string;             // Error message if success=false
+  execution_notes?: string;   // Notes about execution
+}
+
+interface Citation {
+  id: string;                 // e.g., "S1", "S2"
+  source_type: "web" | "document" | "api" | "database" | "manual";
+  title: string;
+  url?: string;
+  accessed_date?: string;     // ISO date
+  excerpt?: string;           // Relevant quote
+}
+```
+
+### Validation Rules
+
+1. `query_id` must exist in `plan.queries`
+2. If `success=true`, `data` should be populated
+3. If `success=false`, `error` should explain why
+4. `sources[].id` should be unique within results
+5. `sources[].id` format: `S1`, `S2`, etc. (gets renumbered to `[1]`, `[2]` in output)
+
+---
+
+## Minimum Viable Test Data
+
+Use this data set for regression testing. It includes 3 patents + 3 web sources.
+
+### Test Plan Input
+
+```json
+{
+  "topic": "optical matrix multiplication",
+  "depth": "shallow",
+  "focus_areas": ["photonic tensor cores"],
+  "output_format": "markdown"
+}
+```
+
+### Test Raw Results (3 patents + 3 web)
+
+```json
+[
+  {
+    "query_id": "q1",
+    "success": true,
+    "data": {
+      "definition": "Optical matrix multiplication performs linear algebra operations using photons instead of electrons, enabling parallel computation at the speed of light.",
+      "characteristics": [
+        "Parallel processing of matrix elements",
+        "Low power consumption",
+        "High bandwidth",
+        "Wavelength division multiplexing"
+      ],
+      "examples": [
+        "Mach-Zehnder interferometer arrays",
+        "Photonic tensor cores",
+        "Optical dot product engines"
+      ]
+    },
+    "sources": [
+      {
+        "id": "S1",
+        "source_type": "document",
+        "title": "US11123456B2 - Optical matrix multiplication system",
+        "url": "https://patents.google.com/patent/US11123456B2",
+        "accessed_date": "2025-01-13",
+        "excerpt": "A system for performing matrix multiplication using coherent optical signals..."
+      },
+      {
+        "id": "S2",
+        "source_type": "web",
+        "title": "Introduction to Photonic Computing - MIT",
+        "url": "https://example.mit.edu/photonic-computing-intro",
+        "accessed_date": "2025-01-13"
+      }
+    ]
+  },
+  {
+    "query_id": "q2",
+    "success": true,
+    "data": {
+      "current_status": "Optical matrix multiplication is transitioning from research to early commercialization, with several startups demonstrating prototype systems.",
+      "recent_developments": [
+        "Lightmatter announced Envise chip (2024)",
+        "Intel demonstrated silicon photonics integration",
+        "NVIDIA exploring hybrid optical-electronic accelerators"
+      ],
+      "key_players": [
+        "Lightmatter",
+        "Luminous Computing",
+        "Intel Silicon Photonics",
+        "MIT Photonics Lab"
+      ]
+    },
+    "sources": [
+      {
+        "id": "S3",
+        "source_type": "document",
+        "title": "US20240001234A1 - Integrated photonic tensor processor",
+        "url": "https://patents.google.com/patent/US20240001234A1",
+        "accessed_date": "2025-01-13",
+        "excerpt": "An integrated photonic processor comprising multiple tensor cores..."
+      },
+      {
+        "id": "S4",
+        "source_type": "web",
+        "title": "Lightmatter Envise Technical Overview",
+        "url": "https://lightmatter.co/envise",
+        "accessed_date": "2025-01-13"
+      }
+    ]
+  },
+  {
+    "query_id": "q3",
+    "success": true,
+    "data": {
+      "items": [
+        "Free-space optical systems",
+        "Integrated photonic circuits",
+        "Hybrid electro-optical systems",
+        "Wavelength-multiplexed arrays"
+      ],
+      "categories": {
+        "Architecture": ["Free-space", "Integrated", "Hybrid"],
+        "Technology": ["Silicon photonics", "III-V compounds", "Polymer waveguides"]
+      }
+    },
+    "sources": [
+      {
+        "id": "S5",
+        "source_type": "document",
+        "title": "EP3987654A1 - Wavelength-multiplexed optical computing",
+        "url": "https://patents.google.com/patent/EP3987654A1",
+        "accessed_date": "2025-01-13",
+        "excerpt": "A wavelength-multiplexed optical computing architecture..."
+      },
+      {
+        "id": "S6",
+        "source_type": "web",
+        "title": "Survey of Optical Computing Architectures - Nature",
+        "url": "https://nature.com/articles/optical-computing-survey",
+        "accessed_date": "2025-01-13"
+      }
+    ]
+  }
+]
+```
+
+### Expected Compile Output Statistics
+
+```json
+{
+  "queries_executed": 3,
+  "queries_succeeded": 3,
+  "queries_failed": 0,
+  "total_sources": 6,
+  "word_count": 300
+}
+```
+
+### Testing Commands
+
+```bash
+# Start the server
+npm run dev
+
+# In another terminal, send test requests via stdio
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | npm run dev
+
+# Or use the MCP inspector
+npx @anthropic/mcp-inspector
+```
+
+---
+
+## Error Cases to Test
+
+### 1. Missing Required Field
+
+```json
+{
+  "depth": "standard"
+}
+```
+Expected: Validation error for missing `topic`
+
+### 2. Invalid Enum Value
+
+```json
+{
+  "topic": "test",
+  "depth": "ultra-deep"
+}
+```
+Expected: Validation error for invalid `depth`
+
+### 3. Failed Query in Results
+
+```json
+{
+  "query_id": "q1",
+  "success": false,
+  "error": "API rate limit exceeded"
+}
+```
+Expected: Warning in output, query skipped in report
+
+### 4. Empty Results Array
+
+```json
+{
+  "plan": { ... },
+  "raw_results": []
+}
+```
+Expected: Empty report with 0 sources, warning about no data