mcp-sequential-research 1.0.0

package/src/format.ts

@@ -0,0 +1,219 @@
+/**
+ * Formatting utilities for sequential research output
+ */
+
+import type { Citation, ReportSection } from "./schema.js";
+
+/**
+ * Generate a unique ID with optional prefix
+ */
+export function generateId(prefix: string = "id"): string {
+  const timestamp = Date.now().toString(36);
+  const random = Math.random().toString(36).substring(2, 8);
+  return `${prefix}-${timestamp}-${random}`;
+}
+
+/**
+ * Get current ISO timestamp
+ */
+export function isoNow(): string {
+  return new Date().toISOString();
+}
+
+/**
+ * Format a citation for inline display
+ */
+export function formatCitationInline(citation: Citation): string {
+  return `[${citation.id}]`;
+}
+
+/**
+ * Format a citation for the sources section
+ */
+export function formatCitationFull(citation: Citation): string {
+  const parts: string[] = [];
+
+  parts.push(`**${citation.id}**:`);
+  parts.push(citation.title);
+
+  if (citation.url) {
+    parts.push(`<${citation.url}>`);
+  }
+
+  if (citation.source_type !== "web") {
+    parts.push(`(${citation.source_type})`);
+  }
+
+  if (citation.accessed_date) {
+    parts.push(`[Accessed: ${citation.accessed_date}]`);
+  }
+
+  return parts.join(" ");
+}
+
+/**
+ * Format a report section as markdown
+ */
+export function formatSection(section: ReportSection): string {
+  const heading = "#".repeat(section.level) + " " + section.heading;
+  return `${heading}\n\n${section.content}`;
+}
+
+/**
+ * Format multiple sections as markdown document
+ */
+export function formatSections(sections: ReportSection[]): string {
+  return sections.map(formatSection).join("\n\n");
+}
+
+/**
+ * Format sources list as markdown
+ */
+export function formatSourcesList(
+  sources: Citation[],
+  style: "inline" | "footnote" | "endnote" = "inline"
+): string {
+  if (sources.length === 0) {
+    return "*No sources cited.*";
+  }
+
+  const lines: string[] = [];
+
+  if (style === "endnote") {
+    lines.push("## Sources\n");
+  } else {
+    lines.push("---\n");
+    lines.push("### References\n");
+  }
+
+  for (const source of sources) {
+    lines.push(`- ${formatCitationFull(source)}`);
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Count words in text (simple whitespace split)
+ */
+export function countWords(text: string): number {
+  return text.split(/\s+/).filter(Boolean).length;
+}
+
+/**
+ * Create a markdown table from data
+ */
+export function formatTable(
+  headers: string[],
+  rows: string[][]
+): string {
+  const headerRow = `| ${headers.join(" | ")} |`;
+  const separator = `| ${headers.map(() => "---").join(" | ")} |`;
+  const dataRows = rows.map((row) => `| ${row.join(" | ")} |`);
+
+  return [headerRow, separator, ...dataRows].join("\n");
+}
+
+/**
+ * Wrap text in a markdown callout/admonition
+ */
+export function formatCallout(
+  content: string,
+  type: "note" | "warning" | "info" | "tip" = "note"
+): string {
+  const icons: Record<string, string> = {
+    note: "📝",
+    warning: "⚠️",
+    info: "ℹ️",
+    tip: "💡",
+  };
+
+  return `> ${icons[type]} **${type.charAt(0).toUpperCase() + type.slice(1)}**\n> \n> ${content.split("\n").join("\n> ")}`;
+}
+
+/**
+ * Escape special markdown characters in text
+ */
+export function escapeMarkdown(text: string): string {
+  return text.replace(/([*_`\[\]()#>+\-.!])/g, "\\$1");
+}
+
+/**
+ * Truncate text to a maximum length with ellipsis
+ */
+export function truncate(text: string, maxLength: number): string {
+  if (text.length <= maxLength) return text;
+  return text.substring(0, maxLength - 3) + "...";
+}
+
+/**
+ * Format a list as markdown bullet points
+ */
+export function formatBulletList(items: string[]): string {
+  return items.map((item) => `- ${item}`).join("\n");
+}
+
+/**
+ * Format a numbered list
+ */
+export function formatNumberedList(items: string[]): string {
+  return items.map((item, i) => `${i + 1}. ${item}`).join("\n");
+}
+
+/**
+ * Create a blockquote
+ */
+export function formatBlockquote(text: string): string {
+  return text
+    .split("\n")
+    .map((line) => `> ${line}`)
+    .join("\n");
+}
+
+/**
+ * Format code block with optional language
+ */
+export function formatCodeBlock(code: string, language: string = ""): string {
+  return `\`\`\`${language}\n${code}\n\`\`\``;
+}
+
+/**
+ * Deduplicate citations by ID
+ */
+export function deduplicateCitations(citations: Citation[]): Citation[] {
+  const seen = new Set<string>();
+  return citations.filter((citation) => {
+    if (seen.has(citation.id)) return false;
+    seen.add(citation.id);
+    return true;
+  });
+}
+
+/**
+ * Renumber citations sequentially
+ */
+export function renumberCitations(
+  citations: Citation[]
+): { citations: Citation[]; mapping: Map<string, string> } {
+  const mapping = new Map<string, string>();
+  const renumbered = citations.map((citation, index) => {
+    const newId = `[${index + 1}]`;
+    mapping.set(citation.id, newId);
+    return { ...citation, id: newId };
+  });
+  return { citations: renumbered, mapping };
+}
+
+/**
+ * Apply citation renumbering to text
+ */
+export function applyCitationMapping(
+  text: string,
+  mapping: Map<string, string>
+): string {
+  let result = text;
+  for (const [oldId, newId] of mapping) {
+    result = result.replaceAll(oldId, newId);
+  }
+  return result;
+}

package/src/index.ts

@@ -0,0 +1,270 @@
+#!/usr/bin/env node
+/**
+ * MCP Sequential Research Server
+ *
+ * Exposes two tools via stdio transport:
+ * - sequential_research_plan: Generate structured research queries
+ * - sequential_research_compile: Compile results into a report
+ */
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+import { PlanInputSchema, CompileInputSchema } from "./schema.js";
+import { generatePlan } from "./planners.js";
+import { compileReport } from "./compilers.js";
+
+// Create MCP server
+const server = new Server(
+  {
+    name: "mcp-sequential-research",
+    version: "1.0.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+// Tool definitions with JSON Schema for MCP
+const TOOLS = [
+  {
+    name: "sequential_research_plan",
+    description: `Generate a structured research plan with queries, extraction goals, and expected result schemas.
+
+Use this tool when:
+- Your prompt involves multiple concepts requiring systematic investigation
+- You need a reproducible search strategy
+- You want query coverage analysis and deduplication guidance
+
+The plan includes:
+- Ordered research queries with priorities and dependencies
+- Extraction goals for each query
+- Expected result schema for validation
+- Execution order (parallel groups)
+
+After receiving the plan, execute queries using appropriate MCP tools (search_patents, Google Custom Search, etc.),
+then pass results to sequential_research_compile.`,
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        topic: {
+          type: "string",
+          description: "The research topic or question to investigate",
+        },
+        depth: {
+          type: "string",
+          enum: ["shallow", "standard", "deep"],
+          default: "standard",
+          description: "Research depth: shallow (3-5 queries), standard (5-10 queries), deep (10-20 queries)",
+        },
+        focus_areas: {
+          type: "array",
+          items: { type: "string" },
+          description: "Specific aspects to focus on (e.g., ['technical details', 'market analysis'])",
+        },
+        constraints: {
+          type: "array",
+          items: { type: "string" },
+          description: "Research constraints or exclusions (e.g., ['no paywalled sources', 'english only'])",
+        },
+        output_format: {
+          type: "string",
+          enum: ["markdown", "json", "structured"],
+          default: "markdown",
+          description: "Desired format for the final compiled output",
+        },
+      },
+      required: ["topic"],
+    },
+  },
+  {
+    name: "sequential_research_compile",
+    description: `Compile research results into a structured markdown report with citations and sources.
+
+Use this tool when:
+- You have executed searches via Google Patents MCP, Google Search MCP, or other sources
+- You want a report with proper citations and risk analysis
+- You need machine-parseable citation references for downstream processing
+
+Input requirements:
+- The original plan from sequential_research_plan
+- Raw results array matching the expected schema (query_id, success, data, sources)
+
+Output includes:
+- Executive summary
+- Organized sections by query type
+- Inline citations [S1], [S2], etc.
+- Consolidated sources table
+- Statistics on query coverage
+
+Citation format: Inline references like [S1] with a sources table at the end for claim-miner compatibility.`,
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        plan: {
+          type: "object",
+          description: "The research plan from sequential_research_plan",
+        },
+        raw_results: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              query_id: { type: "string", description: "Query ID this result corresponds to" },
+              success: { type: "boolean", description: "Whether the query execution succeeded" },
+              data: { type: "object", description: "Extracted data matching the result schema" },
+              sources: {
+                type: "array",
+                items: {
+                  type: "object",
+                  properties: {
+                    id: { type: "string", description: "Citation ID (e.g., S1, S2)" },
+                    source_type: { type: "string", enum: ["web", "document", "api", "database", "manual"] },
+                    title: { type: "string" },
+                    url: { type: "string" },
+                    accessed_date: { type: "string" },
+                    excerpt: { type: "string" },
+                  },
+                  required: ["id", "source_type", "title"],
+                },
+                description: "Sources consulted for this query",
+              },
+              error: { type: "string", description: "Error message if success is false" },
+            },
+            required: ["query_id", "success"],
+          },
+          description: "Raw results from executing the plan queries",
+        },
+        include_sources: {
+          type: "boolean",
+          default: true,
+          description: "Include sources section in output",
+        },
+        include_methodology: {
+          type: "boolean",
+          default: false,
+          description: "Include methodology section in output",
+        },
+        citation_style: {
+          type: "string",
+          enum: ["inline", "footnote", "endnote"],
+          default: "inline",
+          description: "How to format citations in the output",
+        },
+      },
+      required: ["plan", "raw_results"],
+    },
+  },
+];
+
+// Handle list tools request
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: TOOLS,
+  };
+});
+
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    switch (name) {
+      case "sequential_research_plan": {
+        // Validate input
+        const parsed = PlanInputSchema.safeParse(args);
+        if (!parsed.success) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Validation error: ${parsed.error.message}`,
+              },
+            ],
+            isError: true,
+          };
+        }
+
+        // Generate plan
+        const plan = generatePlan(parsed.data);
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(plan, null, 2),
+            },
+          ],
+        };
+      }
+
+      case "sequential_research_compile": {
+        // Validate input
+        const parsed = CompileInputSchema.safeParse(args);
+        if (!parsed.success) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Validation error: ${parsed.error.message}`,
+              },
+            ],
+            isError: true,
+          };
+        }
+
+        // Compile report
+        const report = compileReport(parsed.data);
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(report, null, 2),
+            },
+          ],
+        };
+      }
+
+      default:
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Unknown tool: ${name}`,
+            },
+          ],
+          isError: true,
+        };
+    }
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Error executing ${name}: ${errorMessage}`,
+        },
+      ],
+      isError: true,
+    };
+  }
+});
+
+// Run server
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("MCP Sequential Research server running on stdio");
+}
+
+main().catch((error) => {
+  console.error("Fatal error:", error);
+  process.exit(1);
+});