mcp-sequential-research 1.0.0

package/dist/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"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"}

package/dist/schema.js

@@ -0,0 +1,232 @@
+/**
+ * Zod schemas for MCP Sequential Research tools
+ *
+ * Defines input/output validation for:
+ * - sequential_research_plan
+ * - sequential_research_compile
+ */
+import { z } from "zod";
+// ============================================================================
+// Common Schemas
+// ============================================================================
+/**
+ * Citation reference for tracking source provenance
+ */
+export const CitationSchema = z.object({
+    id: z.string().describe("Unique citation identifier (e.g., [1], [src-001])"),
+    source_type: z.enum(["web", "document", "api", "database", "manual", "patent"]).describe("Type of source"),
+    title: z.string().describe("Title or name of the source"),
+    url: z.string().optional().describe("URL if applicable"),
+    accessed_date: z.string().optional().describe("ISO date when source was accessed"),
+    excerpt: z.string().optional().describe("Relevant excerpt from the source"),
+    // Patent-specific fields
+    patent_number: z.string().optional().describe("Patent number (e.g., US11123456B2)"),
+    assignee: z.string().optional().describe("Patent assignee/owner"),
+    filing_date: z.string().optional().describe("Patent filing date"),
+    priority_date: z.string().optional().describe("Patent priority date"),
+    claims_count: z.number().optional().describe("Number of claims"),
+});
+// ============================================================================
+// Plan Tool Schemas
+// ============================================================================
+/**
+ * Input for sequential_research_plan tool
+ */
+export const PlanInputSchema = z.object({
+    topic: z.string().min(1).describe("The research topic or question to investigate"),
+    depth: z.enum(["shallow", "standard", "deep"]).default("standard").describe("Research depth: shallow (3-5 queries), standard (5-10 queries), deep (10-20 queries)"),
+    focus_areas: z.array(z.string()).optional().describe("Specific aspects to focus on (e.g., ['technical details', 'market analysis'])"),
+    constraints: z.array(z.string()).optional().describe("Research constraints or exclusions (e.g., ['no paywalled sources', 'english only'])"),
+    output_format: z.enum(["markdown", "json", "structured"]).default("markdown").describe("Desired format for the final compiled output"),
+});
+/**
+ * A single research query with extraction goals
+ */
+export const ResearchQuerySchema = z.object({
+    query_id: z.string().describe("Unique identifier for this query (e.g., q1, q2)"),
+    query_text: z.string().describe("The actual search query or question"),
+    query_type: z.enum([
+        // General query types
+        "definition", // What is X?
+        "comparison", // How does X compare to Y?
+        "enumeration", // List all X that...
+        "procedure", // How to do X?
+        "causation", // Why does X happen?
+        "evidence", // What evidence supports X?
+        "current_state", // What is the current state of X?
+        "historical", // History of X
+        "prediction", // Future of X
+        "opinion", // Expert opinions on X
+        // Patent-grade query types
+        "patent_broad", // Broad concept patent search
+        "patent_synonyms", // Alternative terminology/synonyms
+        "patent_problem_benefit", // Problem-solution framing
+        "patent_competitor", // Competitor/assignee search
+        "patent_limitation", // Component-level limitations (narrow novelty)
+        // Web query types for prior art
+        "web_academic", // Academic sources (.edu, .pdf)
+        "web_vendor", // Vendor documentation
+        "web_opensource", // OSS repositories (GitHub, GitLab)
+        "web_conference", // Conference papers (IEEE, ACM, arXiv)
+    ]).describe("Type of query for extraction strategy"),
+    query_family: z.enum(["general", "patent", "web"]).default("general").describe("Query family for source targeting"),
+    extraction_goals: z.array(z.string()).describe("Specific pieces of information to extract from results"),
+    priority: z.enum(["critical", "high", "medium", "low"]).default("medium").describe("Priority level for this query"),
+    depends_on: z.array(z.string()).optional().describe("Query IDs that must complete before this one"),
+    search_modifiers: z.array(z.string()).optional().describe("Search modifiers (e.g., 'site:.edu', 'filetype:pdf', 'assignee:Google')"),
+});
+/**
+ * Schema definition for expected raw results
+ */
+export const RawResultSchemaDefinition = z.object({
+    query_id: z.string().describe("The query this schema applies to"),
+    required_fields: z.array(z.object({
+        field_name: z.string(),
+        field_type: z.enum(["string", "number", "boolean", "array", "object"]),
+        description: z.string(),
+        required: z.boolean().default(true),
+    })).describe("Required fields in the raw result"),
+    example: z.record(z.unknown()).optional().describe("Example of expected result structure"),
+});
+/**
+ * Output from sequential_research_plan tool
+ */
+export const PlanOutputSchema = z.object({
+    plan_id: z.string().describe("Unique identifier for this research plan"),
+    topic: z.string().describe("Original research topic"),
+    created_at: z.string().describe("ISO timestamp when plan was created"),
+    summary: z.string().describe("Brief summary of the research plan"),
+    queries: z.array(ResearchQuerySchema).describe("Ordered list of research queries"),
+    result_schemas: z.array(RawResultSchemaDefinition).describe("Expected schema for each query's raw results"),
+    execution_order: z.array(z.array(z.string())).describe("Grouped query IDs - each group can run in parallel, groups run sequentially"),
+    estimated_sources: z.number().describe("Estimated number of sources to consult"),
+    metadata: z.object({
+        depth: z.string(),
+        focus_areas: z.array(z.string()),
+        constraints: z.array(z.string()),
+        output_format: z.string(),
+    }).describe("Original input parameters preserved for compilation"),
+});
+// ============================================================================
+// Compile Tool Schemas
+// ============================================================================
+/**
+ * Raw result from executing a single query
+ */
+export const RawResultSchema = z.object({
+    query_id: z.string().describe("Query ID this result corresponds to"),
+    success: z.boolean().describe("Whether the query execution succeeded"),
+    data: z.record(z.unknown()).optional().describe("Extracted data matching the result schema"),
+    sources: z.array(CitationSchema).optional().describe("Sources consulted for this query"),
+    error: z.string().optional().describe("Error message if success is false"),
+    execution_notes: z.string().optional().describe("Notes about the execution"),
+});
+/**
+ * Input for sequential_research_compile tool
+ */
+export const CompileInputSchema = z.object({
+    plan: PlanOutputSchema.describe("The research plan to compile results for"),
+    raw_results: z.array(RawResultSchema).describe("Raw results from executing the plan queries"),
+    include_sources: z.boolean().default(true).describe("Include sources section in output"),
+    include_methodology: z.boolean().default(false).describe("Include methodology section"),
+    citation_style: z.enum(["inline", "footnote", "endnote"]).default("inline").describe("How to format citations in the output"),
+});
+/**
+ * A section in the compiled report
+ */
+export const ReportSectionSchema = z.object({
+    heading: z.string().describe("Section heading"),
+    level: z.number().min(1).max(4).describe("Heading level (1-4)"),
+    content: z.string().describe("Section content in markdown"),
+    citations_used: z.array(z.string()).describe("Citation IDs used in this section"),
+});
+/**
+ * Prior art cluster for grouping related sources
+ */
+export const PriorArtClusterSchema = z.object({
+    cluster_id: z.string().describe("Unique cluster identifier"),
+    theme: z.string().describe("Thematic description of the cluster"),
+    source_ids: z.array(z.string()).describe("Citation IDs in this cluster"),
+    relevance: z.enum(["high", "medium", "low"]).describe("Relevance to the research topic"),
+    overlap_notes: z.string().optional().describe("Notes on overlap with target claims"),
+});
+/**
+ * Claim risk flag for potential novelty issues
+ */
+export const ClaimRiskFlagSchema = z.object({
+    risk_id: z.string().describe("Unique risk identifier"),
+    severity: z.enum(["critical", "high", "medium", "low"]).describe("Risk severity"),
+    category: z.enum([
+        "anticipation", // Prior art fully discloses the claim
+        "obviousness", // Combination of references makes claim obvious
+        "enablement", // Specification may not enable full scope
+        "written_description", // Claim may lack written description support
+        "indefiniteness", // Claim terms may be unclear
+    ]).describe("Type of claim risk"),
+    description: z.string().describe("Description of the risk"),
+    affected_elements: z.array(z.string()).optional().describe("Claim elements affected"),
+    blocking_sources: z.array(z.string()).optional().describe("Citation IDs that create this risk"),
+    mitigation: z.string().optional().describe("Suggested mitigation strategy"),
+});
+/**
+ * Novelty gap suggestion for differentiation
+ */
+export const NoveltyGapSchema = z.object({
+    gap_id: z.string().describe("Unique gap identifier"),
+    limitation_type: z.enum([
+        "structural", // Physical/structural difference
+        "functional", // Functional difference
+        "material", // Material composition difference
+        "process", // Method step difference
+        "parameter", // Numerical parameter difference
+        "combination", // Novel combination of known elements
+    ]).describe("Type of limitation"),
+    description: z.string().describe("Description of the potential differentiation"),
+    confidence: z.enum(["high", "medium", "low"]).describe("Confidence in novelty"),
+    supporting_evidence: z.array(z.string()).optional().describe("Citation IDs supporting this gap"),
+    claim_language_suggestion: z.string().optional().describe("Suggested claim language"),
+});
+/**
+ * Output from sequential_research_compile tool
+ */
+export const CompileOutputSchema = z.object({
+    report_id: z.string().describe("Unique identifier for this report"),
+    plan_id: z.string().describe("ID of the plan this report was compiled from"),
+    title: z.string().describe("Report title"),
+    compiled_at: z.string().describe("ISO timestamp when report was compiled"),
+    executive_summary: z.string().describe("Brief executive summary"),
+    sections: z.array(ReportSectionSchema).describe("Report sections"),
+    markdown_report: z.string().describe("Complete markdown-formatted report"),
+    sources: z.array(CitationSchema).describe("Consolidated list of all sources"),
+    statistics: z.object({
+        queries_executed: z.number(),
+        queries_succeeded: z.number(),
+        queries_failed: z.number(),
+        total_sources: z.number(),
+        word_count: z.number(),
+        patent_sources: z.number().optional(),
+        web_sources: z.number().optional(),
+    }).describe("Report statistics"),
+    // Patent-grade analysis outputs
+    prior_art_clusters: z.array(PriorArtClusterSchema).optional().describe("Grouped prior art by theme/relevance"),
+    claim_risk_flags: z.array(ClaimRiskFlagSchema).optional().describe("Identified risks to patentability"),
+    novelty_gaps: z.array(NoveltyGapSchema).optional().describe("Suggested limitations for differentiation"),
+    warnings: z.array(z.string()).optional().describe("Any warnings generated during compilation"),
+});
+// ============================================================================
+// Tool Definitions for MCP
+// ============================================================================
+/**
+ * JSON Schema representations for MCP tool definitions
+ */
+export const toolSchemas = {
+    sequential_research_plan: {
+        input: PlanInputSchema,
+        output: PlanOutputSchema,
+    },
+    sequential_research_compile: {
+        input: CompileInputSchema,
+        output: CompileOutputSchema,
+    },
+};
+//# sourceMappingURL=schema.js.map

package/dist/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"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"}

package/docs/MCP_GUIDANCE.md

@@ -0,0 +1,409 @@
+# MCP Sequential Research Guidance
+
+This document explains when to use each tool and how Claude Code should orchestrate the research workflow.
+
+## When to Use Which Tool
+
+### Use `sequential_research_plan` when:
+
+- **Prompt has multiple concepts** — The research topic spans multiple domains or requires investigating several interrelated ideas (e.g., "Compare transformer architectures for patent classification with attention mechanisms")
+- **You need a reproducible search strategy** — You want a documented, repeatable set of queries that can be audited or re-run later
+- **You want query coverage and dedupe guidance** — The planner identifies overlapping queries and orders them to avoid redundant searches
+- **You're starting a new research task** — Always begin with the plan tool to structure your investigation
+
+### Use `sequential_research_compile` when:
+
+- **You already executed searches** — Via Google Patents MCP (`search_patents`), Google Search MCP (Google Custom Search), or other data sources
+- **You want a report with citations + risk analysis** — The compiler generates structured markdown with machine-parseable citations
+- **You need downstream processing** — The citation format (`[S#]`) is designed for claim-miner compatibility
+
+## How Claude Code Should Run the Workflow
+
+This is the exact **operator loop** Claude Code follows for comprehensive research:
+
+### Complete Workflow Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                    SEQUENTIAL RESEARCH WORKFLOW                      │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                       │
+│  1. PLAN                                                              │
+│     └─→ sequential-research:sequential_research_plan(prompt, constraints) │
+│                        ↓                                              │
+│  2. WEB QUERIES (for each plan.queries where query_family == "web")  │
+│     └─→ google-search:search({query, num: 10})                       │
+│         Returns: {title, link, snippet}[]                            │
+│                        ↓                                              │
+│  3. SCRAPE WEB CONTENT                                               │
+│     ├─→ Collect top URLs (dedupe)                                    │
+│     ├─→ If multiple: firecrawl:firecrawl_batch_scrape({urls})        │
+│     └─→ If single:   firecrawl:firecrawl_scrape({url})               │
+│         Returns: {markdown, metadata}                                │
+│                        ↓                                              │
+│  4. PATENT QUERIES (for each plan.queries where query_family == "patent") │
+│     └─→ google-patents:search_patents({query, num_results})          │
+│         Returns: {patent_number, title, abstract, claims}[]          │
+│                        ↓                                              │
+│  5. NORMALIZE                                                         │
+│     └─→ Transform all results → raw_results[] with S1..Sn IDs        │
+│                        ↓                                              │
+│  6. COMPILE                                                           │
+│     └─→ sequential-research:sequential_research_compile(plan, raw_results) │
+│                        ↓                                              │
+│  7. SAVE                                                              │
+│     ├─→ research/<topic>/report.md                                   │
+│     ├─→ research/<topic>/sources.json                                │
+│     ├─→ research/<topic>/plan.json                                   │
+│     └─→ research/<topic>/raw_results.json                            │
+│                                                                       │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+### Step 1: Generate Research Plan
+
+```json
+{
+  "tool": "sequential-research:sequential_research_plan",
+  "arguments": {
+    "topic": "photonic computing for AI inference acceleration",
+    "depth": "standard",
+    "focus_areas": ["silicon photonics", "energy efficiency", "latency"],
+    "constraints": ["patent-focused", "english only"]
+  }
+}
+```
+
+This returns:
+- Ordered queries with priorities and query families (`general`, `patent`, `web`)
+- Extraction goals per query
+- Expected result schemas
+- Execution order (parallel groups)
+- Search modifiers for each query type
+
+### Step 2: Execute Web Queries via Google Search MCP
+
+For each query where `query_family == "web"`:
+
+```json
+{
+  "tool": "google-search:search",
+  "arguments": {
+    "query": "photonic computing silicon photonics site:.edu OR filetype:pdf",
+    "num": 10
+  }
+}
+```
+
+**Response format:**
+```json
+{
+  "results": [
+    {
+      "title": "Silicon Photonics for AI - MIT",
+      "link": "https://example.mit.edu/photonics.pdf",
+      "snippet": "Recent advances in silicon photonics..."
+    }
+  ]
+}
+```
+
+### Step 3: Scrape Web Content via Firecrawl MCP
+
+After collecting search results, extract full content using Firecrawl.
+
+**For multiple URLs (recommended for efficiency):**
+```json
+{
+  "tool": "firecrawl:firecrawl_batch_scrape",
+  "arguments": {
+    "urls": [
+      "https://example.mit.edu/photonics.pdf",
+      "https://lightmatter.co/technology",
+      "https://ieee.org/article/photonic-computing"
+    ],
+    "options": {
+      "formats": ["markdown"],
+      "onlyMainContent": true
+    }
+  }
+}
+```
+
+**For a single URL:**
+```json
+{
+  "tool": "firecrawl:firecrawl_scrape",
+  "arguments": {
+    "url": "https://example.mit.edu/photonics.pdf",
+    "formats": ["markdown"],
+    "onlyMainContent": true
+  }
+}
+```
+
+**Response format:**
+```json
+{
+  "success": true,
+  "data": {
+    "markdown": "# Silicon Photonics for AI\n\nRecent advances...",
+    "metadata": {
+      "title": "Silicon Photonics for AI",
+      "sourceURL": "https://example.mit.edu/photonics.pdf"
+    }
+  }
+}
+```
+
+### Step 4: Execute Patent Queries via Google Patents MCP
+
+For each query where `query_family == "patent"`:
+
+```json
+{
+  "tool": "google-patents:search_patents",
+  "arguments": {
+    "query": "photonic neural network accelerator",
+    "num_results": 10,
+    "country": "US",
+    "after": "2020-01-01"
+  }
+}
+```
+
+**Response format:**
+```json
+{
+  "patents": [
+    {
+      "patent_number": "US11123456B2",
+      "title": "Photonic Neural Network System",
+      "abstract": "A system for neural network inference...",
+      "assignee": "Intel Corporation",
+      "filing_date": "2021-03-15",
+      "claims": ["1. A photonic computing system comprising..."]
+    }
+  ]
+}
+```
+
+### Step 5: Normalize Results into `raw_results[]`
+
+Transform all responses into the standard schema with sequential source IDs:
+
+```json
+[
+  {
+    "query_id": "q1",
+    "success": true,
+    "data": {
+      "definition": "Photonic computing uses light instead of electrons...",
+      "characteristics": ["Low latency", "High bandwidth", "Energy efficient"],
+      "examples": ["Intel Silicon Photonics", "Lightmatter Envise"]
+    },
+    "sources": [
+      {
+        "id": "S1",
+        "source_type": "patent",
+        "title": "US11123456B2 - Photonic Neural Network System",
+        "url": "https://patents.google.com/patent/US11123456B2",
+        "patent_number": "US11123456B2",
+        "assignee": "Intel Corporation",
+        "filing_date": "2021-03-15",
+        "accessed_date": "2025-01-13",
+        "excerpt": "A photonic computing system comprising an array of Mach-Zehnder interferometers..."
+      },
+      {
+        "id": "S2",
+        "source_type": "web",
+        "title": "Silicon Photonics for AI - MIT",
+        "url": "https://example.mit.edu/photonics.pdf",
+        "accessed_date": "2025-01-13",
+        "excerpt": "Recent advances in silicon photonics have enabled..."
+      }
+    ]
+  }
+]
+```
+
+**Source ID assignment rules:**
+1. Assign `S1`, `S2`, etc. sequentially across all results
+2. Deduplicate URLs before assigning IDs
+3. Patents get `source_type: "patent"` with extra fields
+4. Web content gets `source_type: "web"`
+5. Firecrawl markdown content goes in `excerpt` (truncated if needed)
+
+### Step 6: Call `sequential_research_compile`
+
+```json
+{
+  "tool": "sequential-research:sequential_research_compile",
+  "arguments": {
+    "plan": { /* full plan object from step 1 */ },
+    "raw_results": [ /* array from step 5 */ ],
+    "include_sources": true,
+    "include_methodology": true,
+    "citation_style": "inline"
+  }
+}
+```
+
+### Step 7: Save Outputs
+
+Create the research output directory and save files:
+
+```
+research/<topic-slug>/
+├── report.md        # The compiled markdown report
+├── sources.json     # Structured sources list
+├── plan.json        # Original plan for reproducibility
+└── raw_results.json # Raw data for re-processing
+```
+
+Example file operations:
+```javascript
+// Save all outputs
+await fs.mkdir(`research/${slugify(topic)}`, { recursive: true });
+await fs.writeFile(`research/${slug}/report.md`, output.markdown_report);
+await fs.writeFile(`research/${slug}/sources.json`, JSON.stringify(output.sources, null, 2));
+await fs.writeFile(`research/${slug}/plan.json`, JSON.stringify(plan, null, 2));
+await fs.writeFile(`research/${slug}/raw_results.json`, JSON.stringify(rawResults, null, 2));
+```
+
+---
+
+## MCP Server Integration Reference
+
+| Step | MCP Server | Tool | Purpose |
+|------|-----------|------|---------|
+| 1 | sequential-research | `sequential_research_plan` | Generate structured query plan |
+| 2 | google-search | `search` | Get web search results |
+| 3 | firecrawl | `firecrawl_scrape` / `firecrawl_batch_scrape` | Extract full page content |
+| 4 | google-patents | `search_patents` | Search patent database |
+| 5 | — | — | Normalize to raw_results[] |
+| 6 | sequential-research | `sequential_research_compile` | Generate report with citations |
+| 7 | — | — | Save to filesystem |
+
+---
+
+## Firecrawl Integration Details
+
+### When to Use Batch vs Single Scrape
+
+| Scenario | Tool | Reason |
+|----------|------|--------|
+| 5+ URLs from same query | `firecrawl_batch_scrape` | Efficiency, rate limiting |
+| 1-4 URLs | `firecrawl_scrape` (multiple calls) | Lower overhead |
+| PDF documents | `firecrawl_scrape` | Better PDF handling |
+| Real-time updates needed | `firecrawl_scrape` | Immediate results |
+
+### Firecrawl Options
+
+```json
+{
+  "formats": ["markdown"],        // Output format
+  "onlyMainContent": true,        // Skip headers/footers
+  "includeTags": ["article", "main", "section"],  // Focus on content
+  "excludeTags": ["nav", "footer", "aside"],      // Skip navigation
+  "waitFor": 2000,                // Wait for JS rendering (ms)
+  "timeout": 30000                // Request timeout (ms)
+}
+```
+
+### Handling Firecrawl Errors
+
+```json
+{
+  "query_id": "q3",
+  "success": true,
+  "data": { /* partial data from other sources */ },
+  "sources": [
+    {
+      "id": "S5",
+      "source_type": "web",
+      "title": "Page Title (scrape failed)",
+      "url": "https://example.com/blocked",
+      "excerpt": "[Content unavailable - scrape blocked by robots.txt]"
+    }
+  ],
+  "execution_notes": "1 of 5 URLs failed to scrape"
+}
+```
+
+## Citation Format Requirement
+
+Citations must be **stable** and **machine-parseable** for downstream claim-mining.
+
+### Inline Format
+
+In the body of the report:
+```markdown
+Photonic computing achieves 10x lower latency compared to electronic alternatives [S3].
+The Mach-Zehnder modulator design enables this performance [S3, S7].
+```
+
+### Sources Table Format
+
+At the end of the report:
+```markdown
+## Sources
+
+| ID | Title | URL |
+|----|-------|-----|
+| [S1] | US Patent 11,123,456 - Photonic Neural Processor | https://patents.google.com/patent/US11123456 |
+| [S2] | Lightmatter Technical Brief | https://lightmatter.co/tech |
+| [S3] | Silicon Photonics Benchmarks 2024 | https://example.com/benchmarks |
+```
+
+### Why This Matters
+
+The claim-miner can:
+1. Parse `[S#]` references deterministically
+2. Link claims to specific sources
+3. Generate evidence chains for patent applications
+4. Audit source coverage per claim
+
+## Error Handling
+
+### Failed Queries
+
+If a query fails, include it in `raw_results` with:
+```json
+{
+  "query_id": "q3",
+  "success": false,
+  "error": "Rate limit exceeded on Google Patents API"
+}
+```
+
+The compiler will:
+- Skip failed queries in the report
+- Add warnings to the output
+- Report statistics on query success rate
+
+### Partial Results
+
+If a query partially succeeds, include available data:
+```json
+{
+  "query_id": "q2",
+  "success": true,
+  "data": {
+    "definition": "Found",
+    "characteristics": []  // Empty if not found
+  },
+  "execution_notes": "Only 2 of 5 expected fields populated"
+}
+```
+
+## Best Practices
+
+1. **Always start with a plan** — Even for simple topics, the plan provides structure
+2. **Use parallel execution** — Queries in the same execution group can run concurrently
+3. **Normalize sources immediately** — Convert to standard schema before compile
+4. **Preserve raw data** — Save `raw_results.json` for debugging and re-processing
+5. **Check citation coverage** — Every significant claim should have a `[S#]` reference
+6. **Use stable IDs** — `S1`, `S2`, etc. are more stable than URL-based refs