A community-driven registry for Claude, Cursor, Windsurf, Cline & more. Not affiliated with Anthropic.
Are you the author? Sign in to claim
mcp-occams-razor
Version: 1.7 (Merged with Implementation Details) Author: Boris Djordjevic Date: April 5, 2025 Developed By: 199 Longevity
Large Language Models (LLMs) demonstrate remarkable coding capabilities but often produce solutions that are overly complex, difficult to maintain, or subtly misaligned with user intent. This document describes the Occam's Razor Thinking Tool, a stateless MCP (Model Context Protocol) server component designed to mitigate these issues. It guides LLMs through a structured, sequential thinking process inspired by cognitive science and insights from LLM interpretability research, specifically Anthropic's work on Attribution Graphs [1, 2]. By enforcing distinct stages—Context Analysis, Outcome Definition, Solution Exploration, Simplicity Evaluation, and Implementation—and embedding the principle of Occam's Razor (prioritizing the simplest effective solution) throughout, the tool aims to improve the quality, simplicity, and reliability of LLM-generated code for constructive tasks. It leverages mechanisms analogous to biological processes like parallel exploration, selection pressure, developmental checkpoints, and metacognitive evaluation, translating these concepts into a practical framework for enhanced LLM-driven software development. The design explicitly addresses challenges identified in interpretability research, such as managing computational complexity, handling feature representation issues, and promoting effective goal-directed reasoning.
Large Language Models (LLMs) are increasingly used as powerful coding assistants. However, their unguided application often leads to suboptimal outcomes:
The Occam's Razor Thinking Tool is designed to counteract these tendencies. It provides a structured cognitive workflow delivered via an MCP interface, guiding the LLM through a deliberate sequence of steps before implementation. This framework is built upon two foundational concepts:
By integrating these concepts, the tool promotes the generation of code that is not only functional but also simple, maintainable, and well-reasoned. It achieves this through a single, stateless MCP endpoint for ease of integration.
Implementing and utilizing the Occam's Razor Thinking Tool offers several significant advantages for LLM-assisted software development:
Outcome Definition stage forces clarification of the minimal viable requirements upfront. This drastically reduces the risk of the LLM implementing features that weren't actually requested or misinterpreting the core goal, leading to solutions that are more precisely aligned with user intent.Context Analysis stage ensures that the LLM considers the existing project's architecture, patterns, and constraints before proposing solutions. This leads to generated code that integrates more smoothly with the existing codebase, respects established conventions, and avoids introducing conflicting patterns or unnecessary dependencies.thought for the current stage. This sequence of thoughts creates a traceable record of the LLM's reasoning process, explaining how it arrived at the final solution. This transparency can be invaluable for debugging the process, understanding the rationale behind specific implementation choices, and building trust in the generated code.This server requires Node.js (version 16 or higher recommended). It is published on NPM and designed to be run via npx.
Step 1: Configure Your MCP Client
Add the following JSON block within the "mcpServers": {} object in your client's configuration file. Choose the file corresponding to your client and operating system:
Configuration Block:
"occams-razor": {
"command": "npx",
"args": ["occams-razor-mcp"],
"env": {},
"disabled": false,
"autoApprove": []
}
(Note: Uses the simpler npx <package_name> format. If you encounter issues, try the more explicit format: "args": ["--package", "occams-razor-mcp", "occams-razor-mcp"])
Client Configuration File Locations:
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.json~/.config/Claude/claude_desktop_config.json (Path may vary)~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json~/.cursor/mcp.json.cursor/mcp.json within your project folder.~/.codeium/windsurf/mcp_config.jsonStep 2: Restart Client
After adding the configuration block and saving the file, fully restart your MCP client application. The first time the client starts the server, npx will automatically download the occams-razor-mcp package if needed.
Once installed and enabled, you can instruct your MCP client:
"Use the Occam's Razor tool to add a basic health check endpoint at
/healththat returns a 200 OK status."
The client's AI model should recognize the intent and initiate the multi-step process by calling the occams_razor_thinking tool, starting with the context_analysis stage and proceeding through the defined workflow.
The interaction between the LLM client and the Occam's Razor Thinking Tool server follows a structured cycle. The tool functions as a state machine controller, guiding the LLM sequentially through the defined thinking stages. The LLM calls the tool repeatedly, providing its output ("thought") for the current stage. The tool, being stateless, uses the LLM's input (including the current stage and thought number) to determine and provide the prompt for the next logical step.
The tool guides the LLM through the following mandatory stages:
A final reporting_issue stage is entered if the LLM determines the task is blocked or infeasible.
occams_razor_thinkingThe tool exposes a single endpoint named occams_razor_thinking.
Description: Guides systematic problem-solving for coding tasks using Occam's Razor. Breaks down problems into sequential steps (Context, Outcome, Explore, Evaluate, Implement) prioritizing simplicity. Call this tool sequentially, providing your 'thought' (reasoning/output) for the current step.
Input Parameters: (Refer to src/types.ts or the original PRD for full schema details)
thought (string, required): Detailed thinking/analysis for the current stage.thought_number (integer, required): Sequential number of the thought (starts at 1).thinking_stage (enum, required): The current stage (context_analysis, outcome_definition, etc.).next_thought_needed (boolean, required): true to continue, false to terminate.user_request (string, required on first call): The original user request.needs_clarification (boolean, optional): Set to true if user input is needed.clarification_questions (array, optional): Questions for the user if needs_clarification is true.user_clarification (string, optional): User's response to previous clarification request.requested_stage_override (enum, optional): Target stage for loopback (e.g., solution_exploration).issue_description (string, optional): Summary if task is blocked/infeasible.Output Parameters (Tool Response):
prompt (string): The guidance/instructions for the LLM for the next step or stage.status (enum): Indicates the state of the process after this call (e.g., CONTINUE, CLARIFICATION_NEEDED, LOOPBACK_ACCEPTED, COMPLETED, BLOCKED, ERROR).graph TD
Start[User Coding Request] --> LLM_Call_1[LLM Calls Tool - Stage: Context Analysis];
LLM_Call_1 --> Tool_Resp_1[Tool Responds: Prompt for Outcome Definition];
Tool_Resp_1 --> LLM_Proc_2[LLM Processes Outcome Definition];
LLM_Proc_2 --> NeedClarify{Needs User Clarification?};
NeedClarify -- Yes --> Tool_Resp_Clarify[Tool Responds: Status CLARIFICATION_NEEDED];
Tool_Resp_Clarify --> User_Input[Client Gets User Input];
User_Input --> LLM_Call_Clarify[LLM Calls Tool with User Clarification];
LLM_Call_Clarify --> LLM_Proc_2;
NeedClarify -- No --> Tool_Resp_2[Tool Responds: Prompt for Solution Exploration];
Tool_Resp_2 --> LLM_Proc_3[LLM Processes Solution Exploration];
LLM_Proc_3 --> Tool_Resp_3[Tool Responds: Prompt for Simplicity Evaluation];
Tool_Resp_3 --> LLM_Proc_4[LLM Processes Simplicity Evaluation];
LLM_Proc_4 --> BlockedCheck1{Blocked / Infeasible?};
BlockedCheck1 -- Yes --> LLM_Call_Blocked[LLM Calls Tool - Stage: Reporting Issue, next=false];
LLM_Call_Blocked --> Tool_Resp_Blocked[Tool Responds: Status BLOCKED];
Tool_Resp_Blocked --> End_Blocked([End Process: Blocked]);
BlockedCheck1 -- No --> LoopbackCheck{Loopback Requested & Accepted?};
LoopbackCheck -- Yes --> Tool_Resp_Loopback[Tool Responds: Loopback Prompt for Solution Exploration];
Tool_Resp_Loopback --> LLM_Proc_3;
LoopbackCheck -- No --> Tool_Resp_4[Tool Responds: Prompt for Implementation];
Tool_Resp_4 --> LLM_Proc_5[LLM Processes Implementation Step];
LLM_Proc_5 --> RefineCheck{Needs Refinement / Adaptation?};
RefineCheck -- Yes --> Tool_Resp_Refine[Tool Responds: Prompt for Implementation Refinement];
Tool_Resp_Refine --> LLM_Proc_5;
RefineCheck -- No --> BlockedCheck2{Blocked / Infeasible?};
BlockedCheck2 -- Yes --> LLM_Call_Blocked;
BlockedCheck2 -- No --> LLM_Call_Final[LLM Calls Tool - Stage: Implementation, final summary, next=false];
LLM_Call_Final --> Tool_Resp_Complete[Tool Responds: Status COMPLETED];
Tool_Resp_Complete --> End_Complete([End Process: Completed]);
style End_Blocked fill:#f9f,stroke:#333,stroke-width:2px;
style End_Complete fill:#ccf,stroke:#333,stroke-width:2px;
Summary of Steps:
context_analysis stage.outcome_definition).thought, and calls the tool again.needs_clarification, the tool returns CLARIFICATION_NEEDED, pausing the main flow for user input via the client, which is then passed back to the tool via user_clarification.requested_stage_override (with justification in thought). The tool provides a targeted prompt if the loop is accepted.next_thought_needed: false, resulting in either a COMPLETED or BLOCKED status from the tool.Applying Occam's Razor to software development means actively choosing the simplest design and implementation that effectively fulfills the necessary requirements. In this tool's context, "simplicity" encompasses multiple dimensions evaluated explicitly during the process:
The tool enforces consideration of these factors, particularly during the dedicated simplicity_evaluation stage.
The design choices within this tool are deliberately grounded in findings from LLM interpretability research and analogies to effective cognitive and biological processes. The aim is to create a framework that guides the LLM in a way that resonates with its internal mechanisms and promotes robust, simple problem-solving.
Interpretability techniques, such as those used to generate Attribution Graphs [1, 2], suggest LLMs utilize complex internal strategies, including:
The occams_razor_thinking tool structures the interaction to explicitly invoke and leverage these inferred capabilities. For instance, Solution Exploration taps into parallel processing, Outcome Definition leverages planning, Context Analysis relies on abstraction, and Simplicity Evaluation and clarification handling engage metacognitive judgment. By operating at the level of conceptual stages (e.g., 'Solution Exploration', 'Outcome Definition'), the tool prompts the LLM to synthesize information and present coherent high-level concepts, implicitly managing the potential distribution of underlying computations across many low-level features (analogous to the manual 'supernoding' required in direct circuit analysis [2]). Furthermore, guiding towards simpler solutions proactively aims to foster simpler computational pathways within the LLM itself, reducing the complexity observed in detailed circuit analyses [2].
The tool's stages can be understood through analogies to cognitive and biological processes, informed by the Attribution Graphs research [1, 2]:
needs_clarification): A direct application of metacognition [1], enabling the LLM to signal and resolve uncertainty.requested_stage_override): Provides plasticity and enables error correction. Requiring justification and using specialized loopback prompts referencing the reasons for failure creates an explicit error signal, guiding subsequent attempts more effectively, akin to predictive coding principles [2].thought at each stage is treated as its best attempt to articulate its reasoning, likely reflecting the more structured, explainable parts of its process (analogous to a replacement model view). The tool guides based on this articulation, acknowledging it may be an imperfect or simplified summary of the full internal state.While beneficial, it's important to understand the limitations and scope of this tool:
thought at each step and receiving guidance prompts, inherently uses more tokens per completed task compared to a direct prompt-to-code generation. This cost must be weighed against the potential benefits of improved code quality and reduced rework.thought). Its effectiveness assumes the LLM can access and articulate the internal representations relevant to the task. If the core logic relies on computations poorly captured by the LLM's primary features or falls into its representational gaps ("dark matter" or high reconstruction error scenarios identified in interpretability research [2]), the guidance based on the articulated thoughts might be less effective or even misleading.thought Parameter): The thought provided by the LLM is its attempt to summarize potentially complex internal states and reasoning processes. This articulation is likely subject to the same challenges as human interpretation of LLM features [2] – it may be simplified, miss nuances, or be an imperfect reflection of the underlying computation. The tool operates on this articulated level.git clone https://github.com/199-bio/occams-razor-mcp.git
cd occams-razor-mcp
npm install
npm run build
npm start
ts-node or similar for development:
# npm install -g ts-node (if not installed)
# ts-node src/server.ts
npx command in its configuration.)npm test
npm run lint
npm run format
This tool was developed as part of the initiatives at 199 Longevity, a group focused on extending the frontiers of human health and longevity.
Learn more about our work in biotechnology at 199.bio.
Project contributor: Boris Djordjevic
[1] Olah, C., et al. (2024, February 20). Attribution Graphs. Transformer Circuits. URL: https://transformer-circuits.pub/2025/attribution-graphs/
[2] Ameisen, E., Lindsey, J., Pearce, A., Gurnee, W., Turner, N. L., Chen, B., Citro, C., et al. (2025, March 27). Circuit Tracing: Revealing Computational Graphs in Language Models. Transformer Circuits. URL: https://transformer-circuits.pub/2025/attribution-graphs/methods.html
[3] Olah, C., Cammarata, N., Schubert, L., Goh, G., Petrov, M., & Carter, S. (2020). Zoom In: An Introduction to Circuits. Distill. DOI: 10.23915/distill.00024.001
[4] Gould, S. J., & Vrba, E. S. (1982). Exaptation—a missing term in the science of form. Paleobiology, 8(1), 4-15.
[5] Elhage, N., Nanda, N., Olsson, C., Henighan, T., Joseph, N., Mann, B., Askell, A., Bai, Y., Chen, A., Conerly, T., DasSarma, N., Drain, D., Ganguli, D., Hatfield-Dodds, Z., Hernandez, D., Jones, A., Kernion, J., Lovitt, L., Ndousse, K., Amodei, D., Brown, T., Clark, J., Kaplan, J., McCandlish, S., & Olah, C. (2021). A Mathematical Framework for Transformer Circuits. Transformer Circuits Thread. URL: https://transformer-circuits.pub/2021/framework/index.html
[6] Elhage, N., Hume, T., Olsson, C., Schiefer, N., Henighan, T., Kravec, S., Hatfield-Dodds, Z., Lasenby, R., Drain, D., Chen, C., Grosse, R., McCandlish, S., Kaplan, J., Amodei, D., Wattenberg, M., & Olah, C. (2022). Toy Models of Superposition. Transformer Circuits Thread. URL: https://transformer-circuits.pub/2022/toy_model/index.html
[7] Dunefsky, J., Chlenski, P., & Nanda, N. (2025). Transcoders find interpretable LLM feature circuits. Advances in Neural Information Processing Systems, 37, 24375–24410.
[8] Nikankin, Y., Reusch, A., Mueller, A., & Belinkov, Y. (2024). Arithmetic Without Algorithms: Language Models Solve Math With a Bag of Heuristics. arXiv preprint arXiv:2405.01712.
[9] Bills, S., Cammarata, N., Mossing, D., Tillman, H., Gao, L., Goh, G., Sutskever, I., Leike, J., Wu, J., & Saunders, W. (2023). Language models can explain neurons in language models. OpenAI Blog. URL: https://openai.com/research/language-models-can-explain-neurons-in-language-models
[10] Miller, J., Chughtai, B., & Saunders, W. (2024). Transformer circuit faithfulness metrics are not robust. arXiv preprint arXiv:2407.08734.
MIT License
Copyright (c) 2025 Boris Djordjevic
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
A Jetbrains IDE IntelliJ plugin aimed to provide coding agents the ability to leverage intelliJ's indexing of the codeba
MCP server integration for DaVinci Resolve Studio
Run Claude Code as an MCP server so any agent can delegate coding tasks to it