mcp-sequential-research 1.0.0

package/README.md

@@ -0,0 +1,251 @@
+# mcp-sequential-research
+
+A Model Context Protocol (MCP) server for structured, reproducible research planning and report compilation. Designed for patent prior art research, technical investigations, and systematic literature reviews.
+
+[![npm version](https://img.shields.io/npm/v/mcp-sequential-research.svg)](https://www.npmjs.com/package/mcp-sequential-research)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- **Structured Research Plans** — Generate ordered queries with dependencies, priorities, and extraction goals
+- **Patent-Grade Analysis** — Specialized query families for prior art research (broad, synonyms, competitors, limitations)
+- **Reproducible Workflows** — Deterministic planning without external API calls
+- **Machine-Parseable Citations** — Stable `[S#]` format for downstream claim-mining
+- **Prior Art Clustering** — Automatic grouping of related sources
+- **Claim Risk Analysis** — Flags for potential novelty issues
+- **Zod Validation** — Full TypeScript type safety with runtime validation
+
+## Installation
+
+```bash
+npm install mcp-sequential-research
+```
+
+Or run directly:
+
+```bash
+npx mcp-sequential-research
+```
+
+## Quick Start
+
+### Add to Claude Desktop
+
+Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "sequential-research": {
+      "command": "npx",
+      "args": ["mcp-sequential-research"]
+    }
+  }
+}
+```
+
+### Add to Claude Code
+
+Add to your project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "sequential-research": {
+      "command": "npx",
+      "args": ["mcp-sequential-research"]
+    }
+  }
+}
+```
+
+## Tools
+
+### `sequential_research_plan`
+
+Generates a structured research plan with queries, extraction goals, and expected result schemas.
+
+**When to use:**
+- Multi-concept research topics
+- Prior art investigations
+- Systematic literature reviews
+- When you need reproducible query coverage
+
+**Input:**
+
+```json
+{
+  "topic": "photonic computing for neural network inference",
+  "depth": "standard",
+  "focus_areas": ["silicon photonics", "energy efficiency"],
+  "constraints": ["patent-focused", "post-2020"],
+  "output_format": "markdown"
+}
+```
+
+**Output:**
+- Ordered queries with priorities and dependencies
+- Extraction goals per query
+- Expected result schemas
+- Execution order (parallel groups)
+- Estimated source count
+
+### `sequential_research_compile`
+
+Compiles raw research results into a structured report with citations and analysis.
+
+**When to use:**
+- After executing searches via Google Patents, web search, etc.
+- When you need a citable report
+- For prior art analysis with risk assessment
+
+**Input:**
+
+```json
+{
+  "plan": { /* plan from sequential_research_plan */ },
+  "raw_results": [
+    {
+      "query_id": "q1",
+      "success": true,
+      "data": { /* extracted data */ },
+      "sources": [
+        {
+          "id": "S1",
+          "source_type": "document",
+          "title": "US11123456B2 - Photonic Processor",
+          "url": "https://patents.google.com/patent/US11123456B2"
+        }
+      ]
+    }
+  ],
+  "include_sources": true,
+  "citation_style": "inline"
+}
+```
+
+**Output:**
+- Executive summary
+- Organized report sections
+- Inline citations `[1]`, `[2]`
+- Prior art clusters
+- Claim risk flags
+- Novelty gap suggestions
+- Consolidated sources table
+
+## Patent-Grade Research
+
+This server includes specialized query families for patent prior art research:
+
+### Patent Query Types
+- **Broad concept** — High-level technology area
+- **Synonyms** — Alternative terminology
+- **Problem/benefit framing** — Problem-solution pairs
+- **Competitor/assignee** — Known players in the space
+- **Component-level limitations** — Narrow novelty claims
+
+### Web Query Types
+- **Academic** — `.edu` sites, PDF papers
+- **Vendor documentation** — Technical specifications
+- **Open source** — GitHub, GitLab repositories
+- **Conference papers** — IEEE, ACM, arXiv
+
+### Analysis Features
+- **Prior art clusters** — Grouped related sources
+- **Claim risk flags** — Potential novelty blockers
+- **Novelty gaps** — Suggestions for differentiation
+
+## Workflow Example
+
+```typescript
+// 1. Generate plan
+const plan = await callTool("sequential_research_plan", {
+  topic: "optical matrix multiplication",
+  depth: "standard",
+  focus_areas: ["photonic tensor cores"]
+});
+
+// 2. Execute queries using appropriate MCP tools
+const results = [];
+for (const query of plan.queries) {
+  // Use Google Patents MCP, Google Search MCP, etc.
+  const result = await executeQuery(query);
+  results.push(normalizeResult(query.query_id, result));
+}
+
+// 3. Compile report
+const report = await callTool("sequential_research_compile", {
+  plan,
+  raw_results: results,
+  include_sources: true
+});
+
+// 4. Save outputs
+await saveFile(`research/${slug}/report.md`, report.markdown_report);
+await saveFile(`research/${slug}/sources.json`, report.sources);
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run in development mode
+npm run dev
+
+# Build for production
+npm run build
+
+# Run linter
+npm run lint
+```
+
+## API Reference
+
+See [docs/TOOL_CONTRACTS.md](docs/TOOL_CONTRACTS.md) for complete JSON schemas and test data.
+
+See [docs/MCP_GUIDANCE.md](docs/MCP_GUIDANCE.md) for workflow guidance and best practices.
+
+## Citation Format
+
+All citations use stable, machine-parseable identifiers:
+
+```markdown
+Photonic computing achieves 10x efficiency [1], [2].
+
+---
+### References
+
+| ID | Title | URL |
+|----|-------|-----|
+| [1] | US11123456B2 - Photonic Processor | https://patents.google.com/... |
+| [2] | Silicon Photonics Overview | https://example.com/... |
+```
+
+This format is designed for downstream claim-mining tools.
+
+## Integration
+
+Works with other MCP servers:
+
+| Source Type | Recommended MCP |
+|-------------|-----------------|
+| Patents | Google Patents MCP (`search_patents`) |
+| Web | Google Search MCP (Custom Search) |
+| Memory | Memory MCP (`search_nodes`) |
+| Academic | Semantic Scholar API |
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## Related
+
+- [Model Context Protocol](https://modelcontextprotocol.io/)
+- [@modelcontextprotocol/sdk](https://www.npmjs.com/package/@modelcontextprotocol/sdk)
+- [Claude Code](https://claude.ai/code)

package/dist/compilers.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Research Report Compilation
+ *
+ * Deterministic compiler that transforms research plan + raw results
+ * into a structured markdown report with citations.
+ */
+import type { CompileInput, CompileOutput } from "./schema.js";
+/**
+ * Main compile function
+ */
+export declare function compileReport(input: CompileInput): CompileOutput;
+//# sourceMappingURL=compilers.d.ts.map

package/dist/compilers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compilers.d.ts","sourceRoot":"","sources":["../src/compilers.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,aAAa,EAQd,MAAM,aAAa,CAAC;AA+8BrB;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,YAAY,GAAG,aAAa,CAqHhE"}