verifiable-thinking-mcp 0.4.0

package/src/prompts/templates.ts

@@ -0,0 +1,336 @@
+/**
+ * Pre-built reasoning prompts/templates for common use cases
+ * Guides LLMs on how to use the think tool effectively
+ */
+
+export interface ReasoningTemplate {
+  name: string;
+  description: string;
+  domain: "math" | "logic" | "code" | "general";
+  suggested_steps: number;
+  system_prompt: string;
+}
+
+export const templates: Record<string, ReasoningTemplate> = {
+  "mathematical-proof": {
+    name: "Mathematical Proof",
+    description: "Step-by-step mathematical derivation with verification",
+    domain: "math",
+    suggested_steps: 5,
+    system_prompt: `You are solving a mathematical problem step by step.
+For each step:
+1. State the operation or theorem being applied
+2. Show the transformation clearly
+3. Use verify=true to check arithmetic and algebraic validity
+4. Mark final answer with is_final=true
+
+Enable track_concepts to track mathematical entities (variables, functions, theorems).`,
+  },
+
+  "logical-deduction": {
+    name: "Logical Deduction",
+    description: "Formal logical reasoning with premise validation",
+    domain: "logic",
+    suggested_steps: 4,
+    system_prompt: `You are performing logical deduction.
+For each step:
+1. State premises explicitly
+2. Apply one inference rule per step (modus ponens, modus tollens, etc.)
+3. Use verify=true to check logical consistency
+
+Avoid introducing new premises without justification.`,
+  },
+
+  "code-review": {
+    name: "Code Review",
+    description: "Systematic code analysis for bugs and improvements",
+    domain: "code",
+    suggested_steps: 6,
+    system_prompt: `You are reviewing code for correctness and quality.
+For each step:
+1. Focus on one aspect: syntax, logic, edge cases, performance, security
+2. Quote specific code when identifying issues
+3. Use verify=true to check assertions about code behavior
+4. Use compress_context=true if reviewing large files
+
+Categories to check: null handling, off-by-one errors, resource leaks, error handling, type safety.`,
+  },
+
+  debugging: {
+    name: "Debugging",
+    description: "Systematic bug investigation with hypothesis testing",
+    domain: "code",
+    suggested_steps: 5,
+    system_prompt: `You are debugging a reported issue.
+For each step:
+1. Form a hypothesis about the bug cause
+2. Identify evidence that supports or refutes it
+3. Use branching (branch_id) to explore multiple hypotheses in parallel
+4. Use verify=true to validate assumptions about code behavior
+
+Structure: Symptom → Hypothesis → Evidence → Conclusion → Fix`,
+  },
+
+  "problem-decomposition": {
+    name: "Problem Decomposition",
+    description: "Breaking complex problems into manageable sub-problems",
+    domain: "general",
+    suggested_steps: 4,
+    system_prompt: `You are decomposing a complex problem.
+For each step:
+1. Identify the core question or goal
+2. Break into independent sub-problems where possible
+3. Note dependencies between sub-problems
+4. Use track_concepts=true to maintain a concept graph
+
+Aim for sub-problems that can be solved independently and combined.`,
+  },
+
+  "comparative-analysis": {
+    name: "Comparative Analysis",
+    description: "Systematic comparison of alternatives with trade-offs",
+    domain: "general",
+    suggested_steps: 5,
+    system_prompt: `You are comparing multiple options or approaches.
+For each step:
+1. Define evaluation criteria first
+2. Analyze each option against criteria
+3. Use branch_id to evaluate options in parallel
+4. Synthesize findings with weighted trade-offs
+
+Avoid bias: evaluate all options with same criteria before concluding.`,
+  },
+};
+
+// Prompts for FastMCP - using 'as const' for proper type inference
+export const mathematicalProofPrompt = {
+  name: "mathematical-proof",
+  description: "Guide for step-by-step mathematical proofs with verification",
+  arguments: [
+    {
+      name: "problem",
+      description: "The mathematical problem to solve",
+      required: true,
+    },
+  ] as const,
+  load: async (args: { problem?: string }) => {
+    const template = templates["mathematical-proof"]!;
+    return {
+      messages: [
+        {
+          role: "system" as const,
+          content: {
+            type: "text" as const,
+            text: template.system_prompt,
+          },
+        },
+        {
+          role: "user" as const,
+          content: {
+            type: "text" as const,
+            text: `Problem: ${args.problem || "Not specified"}\n\nUse the 'think' tool with domain="math" and verify=true for each step.`,
+          },
+        },
+      ],
+    };
+  },
+};
+
+export const logicalDeductionPrompt = {
+  name: "logical-deduction",
+  description: "Guide for formal logical reasoning with premise validation",
+  arguments: [
+    {
+      name: "premises",
+      description: "The premises to reason from",
+      required: true,
+    },
+    {
+      name: "conclusion",
+      description: "The conclusion to prove (optional)",
+      required: false,
+    },
+  ] as const,
+  load: async (args: { premises?: string; conclusion?: string }) => {
+    const template = templates["logical-deduction"]!;
+    const goal = args.conclusion ? `Prove: ${args.conclusion}` : "Derive valid conclusions";
+    return {
+      messages: [
+        {
+          role: "system" as const,
+          content: {
+            type: "text" as const,
+            text: template.system_prompt,
+          },
+        },
+        {
+          role: "user" as const,
+          content: {
+            type: "text" as const,
+            text: `Premises:\n${args.premises || "Not specified"}\n\n${goal}\n\nUse the 'think' tool with domain="logic" and verify=true.`,
+          },
+        },
+      ],
+    };
+  },
+};
+
+export const codeReviewPrompt = {
+  name: "code-review",
+  description: "Guide for systematic code review",
+  arguments: [
+    {
+      name: "code",
+      description: "The code to review",
+      required: true,
+    },
+    {
+      name: "focus",
+      description: "Specific focus areas (e.g., security, performance)",
+      required: false,
+    },
+  ] as const,
+  load: async (args: { code?: string; focus?: string }) => {
+    const template = templates["code-review"]!;
+    const focusNote = args.focus ? `Focus on: ${args.focus}` : "";
+    return {
+      messages: [
+        {
+          role: "system" as const,
+          content: {
+            type: "text" as const,
+            text: template.system_prompt,
+          },
+        },
+        {
+          role: "user" as const,
+          content: {
+            type: "text" as const,
+            text: `Review this code:\n\`\`\`\n${args.code || "No code provided"}\n\`\`\`\n${focusNote}\n\nUse the 'think' tool with domain="code" and verify=true.`,
+          },
+        },
+      ],
+    };
+  },
+};
+
+export const debuggingPrompt = {
+  name: "debugging",
+  description: "Guide for systematic bug investigation",
+  arguments: [
+    {
+      name: "symptom",
+      description: "The bug symptom or error message",
+      required: true,
+    },
+    {
+      name: "context",
+      description: "Relevant code or context",
+      required: false,
+    },
+  ] as const,
+  load: async (args: { symptom?: string; context?: string }) => {
+    const template = templates.debugging!;
+    const contextNote = args.context ? `\nContext:\n${args.context}` : "";
+    return {
+      messages: [
+        {
+          role: "system" as const,
+          content: {
+            type: "text" as const,
+            text: template.system_prompt,
+          },
+        },
+        {
+          role: "user" as const,
+          content: {
+            type: "text" as const,
+            text: `Bug symptom: ${args.symptom || "Not specified"}${contextNote}\n\nUse the 'think' tool with domain="code" to investigate.`,
+          },
+        },
+      ],
+    };
+  },
+};
+
+export const problemDecompositionPrompt = {
+  name: "problem-decomposition",
+  description: "Guide for breaking complex problems into sub-problems",
+  arguments: [
+    {
+      name: "problem",
+      description: "The complex problem to decompose",
+      required: true,
+    },
+  ] as const,
+  load: async (args: { problem?: string }) => {
+    const template = templates["problem-decomposition"]!;
+    return {
+      messages: [
+        {
+          role: "system" as const,
+          content: {
+            type: "text" as const,
+            text: template.system_prompt,
+          },
+        },
+        {
+          role: "user" as const,
+          content: {
+            type: "text" as const,
+            text: `Problem: ${args.problem || "Not specified"}\n\nUse the 'think' tool with track_concepts=true to decompose.`,
+          },
+        },
+      ],
+    };
+  },
+};
+
+export const comparativeAnalysisPrompt = {
+  name: "comparative-analysis",
+  description: "Guide for comparing alternatives with trade-offs",
+  arguments: [
+    {
+      name: "options",
+      description: "The options to compare",
+      required: true,
+    },
+    {
+      name: "criteria",
+      description: "Evaluation criteria (optional)",
+      required: false,
+    },
+  ] as const,
+  load: async (args: { options?: string; criteria?: string }) => {
+    const template = templates["comparative-analysis"]!;
+    const criteriaNote = args.criteria ? `\nCriteria: ${args.criteria}` : "";
+    return {
+      messages: [
+        {
+          role: "system" as const,
+          content: {
+            type: "text" as const,
+            text: template.system_prompt,
+          },
+        },
+        {
+          role: "user" as const,
+          content: {
+            type: "text" as const,
+            text: `Compare these options: ${args.options || "Not specified"}${criteriaNote}\n\nUse the 'think' tool with branch_id to evaluate each option.`,
+          },
+        },
+      ],
+    };
+  },
+};
+
+// Export all prompts for registration
+export const allPrompts = [
+  mathematicalProofPrompt,
+  logicalDeductionPrompt,
+  codeReviewPrompt,
+  debuggingPrompt,
+  problemDecompositionPrompt,
+  comparativeAnalysisPrompt,
+];

package/src/resources/index.ts

@@ -0,0 +1,8 @@
+export {
+  allResources,
+  allResourceTemplates,
+  sessionBranchResource,
+  sessionResource,
+  sessionSummaryResource,
+  sessionsListResource,
+} from "./sessions.ts";

package/src/resources/sessions.ts

@@ -0,0 +1,196 @@
+/**
+ * Session Resources - Expose session data as MCP resources
+ * Allows external tools to read reasoning chains
+ */
+
+import { SessionManager } from "../lib/session.ts";
+
+/**
+ * Resource template for accessing individual sessions
+ * URI: session://{session_id}
+ */
+export const sessionResource = {
+  name: "Session",
+  uriTemplate: "session://{session_id}",
+  description:
+    "Access reasoning session data including thoughts, branches, and verification results",
+  mimeType: "application/json",
+  arguments: [
+    {
+      name: "session_id",
+      description: "The session identifier",
+      required: true,
+    },
+  ] as const,
+  load: async (args: { session_id?: string }) => {
+    const sessionId = args.session_id;
+    if (!sessionId) {
+      return {
+        text: JSON.stringify({ error: "session_id is required" }),
+      };
+    }
+
+    const session = SessionManager.get(sessionId);
+    if (!session) {
+      return {
+        text: JSON.stringify({ error: `Session '${sessionId}' not found` }),
+      };
+    }
+
+    const data = {
+      id: session.id,
+      created_at: new Date(session.created_at).toISOString(),
+      updated_at: new Date(session.updated_at).toISOString(),
+      branches: Array.from(session.branches),
+      thought_count: session.thoughts.length,
+      thoughts: session.thoughts.map((t) => ({
+        id: t.id,
+        step_number: t.step_number,
+        branch_id: t.branch_id,
+        thought: t.thought,
+        timestamp: new Date(t.timestamp).toISOString(),
+        verification: t.verification,
+        concepts: t.concepts,
+      })),
+      metadata: session.metadata,
+    };
+
+    return {
+      text: JSON.stringify(data, null, 2),
+    };
+  },
+};
+
+/**
+ * Resource template for session summaries
+ * URI: session://{session_id}/summary
+ */
+export const sessionSummaryResource = {
+  name: "Session Summary",
+  uriTemplate: "session://{session_id}/summary",
+  description: "Get a text summary of a reasoning session",
+  mimeType: "text/plain",
+  arguments: [
+    {
+      name: "session_id",
+      description: "The session identifier",
+      required: true,
+    },
+  ] as const,
+  load: async (args: { session_id?: string }) => {
+    const sessionId = args.session_id;
+    if (!sessionId) {
+      return { text: "Error: session_id is required" };
+    }
+
+    const summary = SessionManager.getSummary(sessionId);
+    if (!summary) {
+      return { text: `Error: Session '${sessionId}' not found` };
+    }
+
+    return { text: summary };
+  },
+};
+
+/**
+ * Resource template for session branch data
+ * URI: session://{session_id}/branch/{branch_id}
+ */
+export const sessionBranchResource = {
+  name: "Session Branch",
+  uriTemplate: "session://{session_id}/branch/{branch_id}",
+  description: "Access thoughts from a specific branch in a session",
+  mimeType: "application/json",
+  arguments: [
+    {
+      name: "session_id",
+      description: "The session identifier",
+      required: true,
+    },
+    {
+      name: "branch_id",
+      description: "The branch identifier (default: main)",
+      required: false,
+    },
+  ] as const,
+  load: async (args: { session_id?: string; branch_id?: string }) => {
+    const sessionId = args.session_id;
+    const branchId = args.branch_id || "main";
+
+    if (!sessionId) {
+      return {
+        text: JSON.stringify({ error: "session_id is required" }),
+      };
+    }
+
+    const thoughts = SessionManager.getThoughts(sessionId, branchId);
+    if (thoughts.length === 0) {
+      const session = SessionManager.get(sessionId);
+      if (!session) {
+        return {
+          text: JSON.stringify({ error: `Session '${sessionId}' not found` }),
+        };
+      }
+      return {
+        text: JSON.stringify({
+          error: `Branch '${branchId}' not found or empty`,
+          available_branches: Array.from(session.branches),
+        }),
+      };
+    }
+
+    const data = {
+      session_id: sessionId,
+      branch_id: branchId,
+      thought_count: thoughts.length,
+      thoughts: thoughts.map((t) => ({
+        id: t.id,
+        step_number: t.step_number,
+        thought: t.thought,
+        timestamp: new Date(t.timestamp).toISOString(),
+        verification: t.verification,
+        concepts: t.concepts,
+      })),
+    };
+
+    return {
+      text: JSON.stringify(data, null, 2),
+    };
+  },
+};
+
+/**
+ * Static resource listing all active sessions
+ */
+export const sessionsListResource = {
+  name: "Sessions List",
+  uri: "session://list",
+  description: "List all active reasoning sessions",
+  mimeType: "application/json",
+  load: async () => {
+    const sessions = SessionManager.list();
+
+    const data = {
+      count: sessions.length,
+      sessions: sessions.map((s) => ({
+        id: s.id,
+        thought_count: s.thought_count,
+        branches: s.branches,
+        age_seconds: Math.round(s.age_ms / 1000),
+      })),
+    };
+
+    return {
+      text: JSON.stringify(data, null, 2),
+    };
+  },
+};
+
+// Export all resources
+export const allResources = [sessionsListResource];
+
+export const allResourceTemplates = [
+  sessionResource,
+  sessionSummaryResource,
+  sessionBranchResource,
+];

package/src/tools/compress.ts

@@ -0,0 +1,138 @@
+import { z } from "zod";
+import { type CompressionResult, compress, quickCompress } from "../lib/compression.ts";
+import { calculateTokenUsage } from "../lib/tokens.ts";
+
+/**
+ * Standalone compress tool - Enhanced CPC-style context compression
+ * Features: TF-IDF, NCD relevance, coreference/causal constraints, filler removal
+ */
+export const compressTool = {
+  name: "compress",
+  description: `Compress context using enhanced CPC-style sentence-level relevance scoring.
+
+Features:
+- TF-IDF + NCD (gzip-based) query relevance scoring
+- Coreference constraints (keeps pronoun antecedents)
+- Causal chain preservation (keeps premises for "therefore" etc.)
+- Filler/meta-cognition removal
+- Repetition detection and penalization
+
+Up to 10x faster than token-level compression methods. Keeps sentences most relevant 
+to the query while maintaining coherence by preserving original sentence order.
+
+Use this to reduce token costs before sending large contexts to LLMs.`,
+
+  parameters: z.object({
+    context: z
+      .string()
+      .max(1_000_000, "Context exceeds 1MB limit - split into smaller chunks")
+      .describe("The text/context to compress"),
+    query: z
+      .string()
+      .max(10_000, "Query exceeds 10KB limit")
+      .describe("Focus query - sentences relevant to this are kept"),
+    target_ratio: z
+      .number()
+      .min(0.1)
+      .max(1.0)
+      .default(0.5)
+      .describe("Target compression ratio (0.5 = keep ~50%)"),
+    max_tokens: z
+      .number()
+      .int()
+      .min(50)
+      .optional()
+      .describe("Alternative: specify max tokens instead of ratio"),
+    boost_reasoning: z
+      .boolean()
+      .default(true)
+      .describe("Boost sentences with reasoning keywords (therefore, because, etc.)"),
+    use_ncd: z.boolean().default(true).describe("Use NCD (gzip-based) query similarity scoring"),
+    enforce_coref: z
+      .boolean()
+      .default(true)
+      .describe("Keep antecedent sentences when pronouns are selected"),
+    enforce_causal: z
+      .boolean()
+      .default(true)
+      .describe("Keep premise sentences when causal conclusions are selected"),
+    remove_fillers: z
+      .boolean()
+      .default(true)
+      .describe("Remove filler phrases (basically, actually, let me think, etc.)"),
+  }),
+
+  execute: async (args: {
+    context: string;
+    query: string;
+    target_ratio?: number;
+    max_tokens?: number;
+    boost_reasoning?: boolean;
+    use_ncd?: boolean;
+    enforce_coref?: boolean;
+    enforce_causal?: boolean;
+    remove_fillers?: boolean;
+  }): Promise<string> => {
+    let result: CompressionResult;
+
+    // Use max_tokens mode if specified
+    if (args.max_tokens) {
+      const compressed = quickCompress(args.context, args.query, args.max_tokens);
+      const originalTokens = Math.ceil(args.context.length / 4);
+      const compressedTokens = Math.ceil(compressed.length / 4);
+
+      result = {
+        compressed,
+        original_tokens: originalTokens,
+        compressed_tokens: compressedTokens,
+        ratio: compressed.length / args.context.length,
+        kept_sentences: compressed.split(/(?<=[.!?])\s+/).length,
+        dropped_sentences: [],
+      };
+    } else {
+      // Standard ratio-based compression with all options
+      result = compress(args.context, args.query, {
+        target_ratio: args.target_ratio ?? 0.5,
+        boost_reasoning: args.boost_reasoning ?? true,
+        useNCD: args.use_ncd ?? true,
+        enforceCoref: args.enforce_coref ?? true,
+        enforceCausalChains: args.enforce_causal ?? true,
+        removeFillers: args.remove_fillers ?? true,
+      });
+    }
+
+    const output = formatCompressResult(result);
+    const tokens = calculateTokenUsage(args, output);
+
+    return `${output}\n\n---\n_tokens: ${tokens.input_tokens} in, ${tokens.output_tokens} out, ${tokens.total_tokens} total_`;
+  },
+};
+
+function formatCompressResult(result: CompressionResult): string {
+  const savings = Math.round((1 - result.ratio) * 100);
+
+  const lines = [
+    `**Compression Results**`,
+    `- Tokens: ${result.original_tokens} → ${result.compressed_tokens} (${savings}% reduction)`,
+    `- Sentences kept: ${result.kept_sentences}`,
+    `- Sentences dropped: ${result.dropped_sentences.length}`,
+  ];
+
+  // Add enhancement details if present
+  if (result.enhancements) {
+    const enh = result.enhancements;
+    const enhParts: string[] = [];
+    if (enh.fillers_removed > 0) enhParts.push(`fillers=${enh.fillers_removed}`);
+    if (enh.coref_constraints_applied > 0) enhParts.push(`coref=${enh.coref_constraints_applied}`);
+    if (enh.causal_constraints_applied > 0)
+      enhParts.push(`causal=${enh.causal_constraints_applied}`);
+    if (enh.repetitions_penalized > 0) enhParts.push(`repetitions=${enh.repetitions_penalized}`);
+    if (enhParts.length > 0) {
+      lines.push(`- Enhancements: ${enhParts.join(", ")}`);
+    }
+  }
+
+  lines.push(``, `**Compressed Context:**`, result.compressed);
+
+  return lines.join("\n");
+}

package/src/tools/index.ts

@@ -0,0 +1,5 @@
+// Re-export SessionManager for hint state access
+export { SessionManager } from "../lib/session.ts";
+export { compressTool } from "./compress.ts";
+export { scratchpadTool } from "./scratchpad.ts";
+export { clearSessionTool, getSessionTool, listSessionsTool } from "./sessions.ts";