Shannon Thinking MCP Server

Instructions

Implementation Reference

• src/server.ts:205-272 (handler)

  The core handler function that executes the shannonthinking tool logic: validates input, checks dependencies and revisions, stores thought in history, formats for console, and returns structured JSON response with status.
  public processThought(input: unknown): { content: Array<{ type: string; text: string }>; isError?: boolean } { try { const validatedInput = this.validateThoughtData(input); if (validatedInput.thoughtNumber > validatedInput.totalThoughts) { validatedInput.totalThoughts = validatedInput.thoughtNumber; } // Validate dependencies and revisions for (const depNumber of validatedInput.dependencies) { if (depNumber >= validatedInput.thoughtNumber) { throw new Error(`Invalid dependency: cannot depend on future thought ${depNumber}`); } if (!this.thoughtHistory.some(t => t.thoughtNumber === depNumber)) { throw new Error(`Invalid dependency: thought ${depNumber} does not exist`); } } // Validate revision target if (validatedInput.isRevision && validatedInput.revisesThought !== undefined) { if (validatedInput.revisesThought >= validatedInput.thoughtNumber) { throw new Error(`Invalid revision: cannot revise future thought ${validatedInput.revisesThought}`); } if (!this.thoughtHistory.some(t => t.thoughtNumber === validatedInput.revisesThought)) { throw new Error(`Invalid revision: thought ${validatedInput.revisesThought} does not exist`); } } this.thoughtHistory.push(validatedInput); const formattedThought = this.formatThought(validatedInput); console.error(formattedThought); return { content: [{ type: "text", text: JSON.stringify({ thoughtNumber: validatedInput.thoughtNumber, totalThoughts: validatedInput.totalThoughts, nextThoughtNeeded: validatedInput.nextThoughtNeeded, thoughtType: validatedInput.thoughtType, uncertainty: validatedInput.uncertainty, thoughtHistoryLength: this.thoughtHistory.length, isRevision: validatedInput.isRevision, revisesThought: validatedInput.revisesThought, hasExperimentalValidation: !!validatedInput.experimentalElements, hasRecheckStep: !!validatedInput.recheckStep }, null, 2) }] }; } catch (error) { return { content: [{ type: "text", text: JSON.stringify({ error: error instanceof Error ? error.message : String(error), details: { receivedInput: JSON.stringify(input, null, 2), thoughtHistoryLength: this.thoughtHistory.length, lastValidThought: this.thoughtHistory.length > 0 ? this.thoughtHistory[this.thoughtHistory.length - 1].thoughtNumber : null }, status: 'failed' }, null, 2) }], isError: true }; } }
• src/index.ts:20-205 (schema)

  Full tool definition including name, detailed description, and comprehensive input JSON schema defining all parameters for Shannon thinking steps.
  const SHANNON_THINKING_TOOL: Tool = { name: "shannonthinking", description: `A problem-solving tool inspired by Claude Shannon's systematic and iterative approach to complex problems. This tool helps break down problems using Shannon's methodology of problem definition, mathematical modeling, validation, and practical implementation. When to use this tool: - Complex system analysis - Information processing problems - Engineering design challenges - Problems requiring theoretical frameworks - Optimization problems - Systems requiring practical implementation - Problems that need iterative refinement - Cases where experimental validation complements theory Key features: - Systematic progression through problem definition → constraints → modeling → validation → implementation - Support for revising earlier steps as understanding evolves - Ability to mark steps for re-examination with new information - Experimental validation alongside formal proofs - Explicit tracking of assumptions and dependencies - Confidence levels for each step - Rich feedback and validation results Parameters explained: - thoughtType: Type of thinking step (PROBLEM_DEFINITION, CONSTRAINTS, MODEL, PROOF, IMPLEMENTATION) - uncertainty: Confidence level in the current thought (0-1) - dependencies: Which previous thoughts this builds upon - assumptions: Explicit listing of assumptions made - isRevision: Whether this revises an earlier thought - revisesThought: Which thought is being revised - recheckStep: For marking steps that need re-examination - proofElements: For formal validation steps - experimentalElements: For empirical validation - implementationNotes: For practical application steps The tool supports an iterative approach: 1. Define the problem's fundamental elements (revisable as understanding grows) 2. Identify system constraints and limitations (can be rechecked with new information) 3. Develop mathematical/theoretical models 4. Validate through proofs and/or experimental testing 5. Design and test practical implementations Each thought can build on, revise, or re-examine previous steps, creating a flexible yet rigorous problem-solving framework.`, inputSchema: { type: "object", properties: { thought: { type: "string", description: "Your current thinking step" }, thoughtType: { type: "string", enum: Object.values(ThoughtType), description: "Type of thinking step" }, thoughtNumber: { type: "integer", description: "Current thought number", minimum: 1 }, totalThoughts: { type: "integer", description: "Estimated total thoughts needed", minimum: 1 }, uncertainty: { type: "number", description: "Confidence level (0-1)", minimum: 0, maximum: 1 }, dependencies: { type: "array", items: { type: "integer", minimum: 1 }, description: "Thought numbers this builds upon" }, assumptions: { type: "array", items: { type: "string" }, description: "Explicit list of assumptions" }, nextThoughtNeeded: { type: "boolean", description: "Whether another thought step is needed" }, isRevision: { type: "boolean", description: "Whether this thought revises an earlier one" }, revisesThought: { type: "integer", description: "The thought number being revised", minimum: 1 }, recheckStep: { type: "object", properties: { stepToRecheck: { type: "string", enum: Object.values(ThoughtType), description: "Which type of step needs re-examination" }, reason: { type: "string", description: "Why the step needs to be rechecked" }, newInformation: { type: "string", description: "New information prompting the recheck" } }, required: ["stepToRecheck", "reason"], description: "For marking steps that need re-examination" }, proofElements: { type: "object", properties: { hypothesis: { type: "string", description: "The hypothesis being tested" }, validation: { type: "string", description: "How the hypothesis was validated" } }, required: ["hypothesis", "validation"], description: "Elements required for formal proof steps" }, experimentalElements: { type: "object", properties: { testDescription: { type: "string", description: "Description of the experimental test" }, results: { type: "string", description: "Results of the experiment" }, confidence: { type: "number", description: "Confidence in the experimental results (0-1)", minimum: 0, maximum: 1 }, limitations: { type: "array", items: { type: "string" }, description: "Limitations of the experimental validation" } }, required: ["testDescription", "results", "confidence", "limitations"], description: "Elements for experimental validation" }, implementationNotes: { type: "object", properties: { practicalConstraints: { type: "array", items: { type: "string" }, description: "List of practical limitations and constraints" }, proposedSolution: { type: "string", description: "Detailed implementation proposal" } }, required: ["practicalConstraints", "proposedSolution"], description: "Notes for practical implementation steps" } }, required: ["thought", "thoughtType", "thoughtNumber", "totalThoughts", "uncertainty", "dependencies", "assumptions", "nextThoughtNeeded"] } };
• src/index.ts:221-237 (registration)

  Registers the shannonthinking tool in the MCP server for both listing available tools and handling tool calls by delegating to ShannonThinkingServer.processThought.
  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [SHANNON_THINKING_TOOL], })); server.setRequestHandler(CallToolRequestSchema, async (request) => { if (request.params.name === "shannonthinking") { return thinkingServer.processThought(request.params.arguments); } return { content: [{ type: "text", text: `Unknown tool: ${request.params.name}` }], isError: true }; });
• src/types.ts:1-39 (schema)

  TypeScript type definitions for ThoughtType enum and ShannonThoughtData interface that underpin the tool's input schema and validation.
  export enum ThoughtType { PROBLEM_DEFINITION = 'problem_definition', CONSTRAINTS = 'constraints', MODEL = 'model', PROOF = 'proof', IMPLEMENTATION = 'implementation' } export interface ShannonThoughtData { thought: string; thoughtType: ThoughtType; thoughtNumber: number; totalThoughts: number; uncertainty: number; // 0-1 dependencies: number[]; // thought numbers this builds on assumptions: string[]; // explicit list of assumptions nextThoughtNeeded: boolean; recheckStep?: { stepToRecheck: ThoughtType; reason: string; newInformation?: string; }; proofElements?: { hypothesis: string; validation: string; }; experimentalElements?: { testDescription: string; results: string; confidence: number; // 0-1 limitations: string[]; }; implementationNotes?: { practicalConstraints: string[]; proposedSolution: string; }; isRevision?: boolean; revisesThought?: number; }
• src/server.ts:7-117 (helper)

  Helper method that performs detailed runtime validation of input parameters against the expected ShannonThoughtData structure, throwing descriptive errors for invalid fields.
  private validateThoughtData(input: unknown): ShannonThoughtData { const data = input as Record<string, unknown>; if (!data.thought || typeof data.thought !== 'string') { throw new Error(`Invalid thought: must be a string, received ${typeof data.thought}`); } if (!data.thoughtType || !Object.values(ThoughtType).includes(data.thoughtType as ThoughtType)) { throw new Error(`Invalid thoughtType: must be one of: ${Object.values(ThoughtType).join(', ')}, received ${data.thoughtType}`); } if (!data.thoughtNumber || typeof data.thoughtNumber !== 'number') { throw new Error(`Invalid thoughtNumber: must be a number, received ${typeof data.thoughtNumber}`); } if (!data.totalThoughts || typeof data.totalThoughts !== 'number') { throw new Error(`Invalid totalThoughts: must be a number, received ${typeof data.totalThoughts}`); } if (typeof data.uncertainty !== 'number' || data.uncertainty < 0 || data.uncertainty > 1) { throw new Error(`Invalid uncertainty: must be a number between 0 and 1, received ${data.uncertainty}`); } if (!Array.isArray(data.dependencies)) { throw new Error(`Invalid dependencies: must be an array, received ${typeof data.dependencies}`); } if (!Array.isArray(data.assumptions)) { throw new Error(`Invalid assumptions: must be an array, received ${typeof data.assumptions}`); } if (typeof data.nextThoughtNeeded !== 'boolean') { throw new Error(`Invalid nextThoughtNeeded: must be a boolean, received ${typeof data.nextThoughtNeeded}`); } // Optional recheckStep validation if (data.recheckStep) { const recheck = data.recheckStep as Record<string, unknown>; if (!recheck.stepToRecheck || !Object.values(ThoughtType).includes(recheck.stepToRecheck as ThoughtType)) { throw new Error('Invalid recheckStep: stepToRecheck must be a valid ThoughtType'); } if (!recheck.reason || typeof recheck.reason !== 'string') { throw new Error('Invalid recheckStep: reason must be a string'); } if (recheck.newInformation && typeof recheck.newInformation !== 'string') { throw new Error('Invalid recheckStep: newInformation must be a string if provided'); } } // Optional proofElements validation if (data.proofElements) { const proof = data.proofElements as Record<string, unknown>; if (!proof.hypothesis || typeof proof.hypothesis !== 'string') { throw new Error('Invalid proofElements: hypothesis must be a string'); } if (!proof.validation || typeof proof.validation !== 'string') { throw new Error('Invalid proofElements: validation must be a string'); } } // Optional experimentalElements validation if (data.experimentalElements) { const exp = data.experimentalElements as Record<string, unknown>; if (!exp.testDescription || typeof exp.testDescription !== 'string') { throw new Error('Invalid experimentalElements: testDescription must be a string'); } if (!exp.results || typeof exp.results !== 'string') { throw new Error('Invalid experimentalElements: results must be a string'); } if (typeof exp.confidence !== 'number' || exp.confidence < 0 || exp.confidence > 1) { throw new Error('Invalid experimentalElements: confidence must be a number between 0 and 1'); } if (!Array.isArray(exp.limitations)) { throw new Error('Invalid experimentalElements: limitations must be an array'); } } // Optional implementationNotes validation if (data.implementationNotes) { const impl = data.implementationNotes as Record<string, unknown>; if (!Array.isArray(impl.practicalConstraints)) { throw new Error('Invalid implementationNotes: practicalConstraints must be an array'); } if (!impl.proposedSolution || typeof impl.proposedSolution !== 'string') { throw new Error('Invalid implementationNotes: proposedSolution must be a string'); } } // Optional revision validation if (data.isRevision !== undefined && typeof data.isRevision !== 'boolean') { throw new Error('Invalid isRevision: must be a boolean if provided'); } if (data.revisesThought !== undefined) { if (typeof data.revisesThought !== 'number' || data.revisesThought < 1) { throw new Error('Invalid revisesThought: must be a positive number if provided'); } if (!data.isRevision) { throw new Error('Invalid revisesThought: cannot be set without isRevision being true'); } } return { thought: data.thought as string, thoughtType: data.thoughtType as ThoughtType, thoughtNumber: data.thoughtNumber as number, totalThoughts: data.totalThoughts as number, uncertainty: data.uncertainty as number, dependencies: data.dependencies as number[], assumptions: data.assumptions as string[], nextThoughtNeeded: data.nextThoughtNeeded as boolean, recheckStep: data.recheckStep as ShannonThoughtData['recheckStep'], proofElements: data.proofElements as ShannonThoughtData['proofElements'], experimentalElements: data.experimentalElements as ShannonThoughtData['experimentalElements'], implementationNotes: data.implementationNotes as ShannonThoughtData['implementationNotes'], isRevision: data.isRevision as boolean | undefined, revisesThought: data.revisesThought as number | undefined, }; }