mcp-sequential-research 1.0.0

package/src/schema.ts

@@ -0,0 +1,303 @@
+/**
+ * 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"),
+});
+
+export type Citation = z.infer<typeof CitationSchema>;
+
+// ============================================================================
+// 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"
+  ),
+});
+
+export type PlanInput = z.infer<typeof PlanInputSchema>;
+
+/**
+ * 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')"
+  ),
+});
+
+export type ResearchQuery = z.infer<typeof ResearchQuerySchema>;
+
+/**
+ * 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"),
+});
+
+export type RawResultSchemaDefinition = z.infer<typeof RawResultSchemaDefinition>;
+
+/**
+ * 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"),
+});
+
+export type PlanOutput = z.infer<typeof PlanOutputSchema>;
+
+// ============================================================================
+// 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"),
+});
+
+export type RawResult = z.infer<typeof RawResultSchema>;
+
+/**
+ * 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"
+  ),
+});
+
+export type CompileInput = z.infer<typeof CompileInputSchema>;
+
+/**
+ * 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"),
+});
+
+export type ReportSection = z.infer<typeof ReportSectionSchema>;
+
+/**
+ * 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"),
+});
+
+export type PriorArtCluster = z.infer<typeof PriorArtClusterSchema>;
+
+/**
+ * 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"),
+});
+
+export type ClaimRiskFlag = z.infer<typeof ClaimRiskFlagSchema>;
+
+/**
+ * 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"),
+});
+
+export type NoveltyGap = z.infer<typeof NoveltyGapSchema>;
+
+/**
+ * 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"),
+});
+
+export type CompileOutput = z.infer<typeof CompileOutputSchema>;
+
+// ============================================================================
+// 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,
+  },
+} as const;

package/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "resolveJsonModule": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}