Think Tool

A Model Context Protocol (MCP) server that provides a "reflect" tool for AI assistants to create cognitive checkpoints and structured reasoning. This tool helps LLMs maintain context, reflect on their work, and think through complex problems systematically.

Key Insight:Without explicitly outputting thought processes, no deep thinking occurs. This tool creates mandatory cognitive checkpoints that prevent shortcuts and improve accuracy.

- 🧠Structured Reasoning: Forces AI assistants to reflect step-by-step through complex problems
- ✅Task Validation: Creates checkpoints to verify requirements are met
- 📝Learning Documentation: Captures discoveries and insights during problem-solving
- 🔍Debugging Aid: Helps work through issues systematically by elimination
- 🎯Decision Audit Trail: Creates a record of reasoning for important decisions

# Install globally npm install -g mcp-reflection-tool # Or run directly with npx (no installation needed) npx mcp-reflection-tool

This will automatically configure the server in your Claude Code settings. After running the command, restart Claude Code completely.
- Open Cursor Settings (Cmd/Ctrl + ,)
- Search for "MCP" or navigate to Features > MCP
- Add the reflection tool configuration

{ "mcpServers": { "reflection-tool": { "command": "npx", "args": ["mcp-reflection-tool"] } } }

Location:~/.windsurf/mcp.json(macOS/Linux) or%USERPROFILE%\.windsurf\mcp.json(Windows)

{ "mcpServers": { "reflection-tool": { "command": "npx", "args": ["mcp-reflection-tool"] } } }

- Open VS Code Settings (Cmd/Ctrl + ,)
- Search for "Cline MCP"
- Add server configuration

{ "cline.mcpServers": { "reflection-tool": { "command": "npx", "args": ["mcp-reflection-tool"] } } }

Reload VS Code window after configuration.

The server runs via stdio by default. If you need HTTP mode, use environment variables:

# Start server in stdio mode (default) npx mcp-reflection-tool # Start in HTTP mode on port 8080 HTTP=true npx mcp-reflection-tool # Start in HTTP mode on custom port HTTP=true PORT=3000 npx mcp-reflection-tool

Most modern AI tools support stdio mode automatically.

Once installed, the AI assistant will have access to thereflecttool. Here are examples of how it gets used:

Using reflection tool: "Breaking down authentication implementation: 1. Check existing auth patterns in codebase 2. Set up JWT token generation 3. Add middleware for route protection 4. Test with valid and expired tokens"

Using reflection tool: "Task completion check: - Completed: Implemented user authentication with JWT - Learned: Existing middleware made integration smooth - Technical debt: Need to add rate limiting - Next: Update API documentation"

Using reflection tool: "Debugging slow API responses: - Symptom: 5+ second response times - Hypothesis 1: Missing database indexes - CONFIRMED - Hypothesis 2: N+1 query problem - Also found - Solution: Added compound indexes and query batching - Result: Response time now <200ms"

The AI assistant will automatically use this tool as a cognitive scratchpad for:

- 🔍Chain-of-thought reasoningthrough complex problems
- 📋Planning your approachbefore taking actions
- ✅Reflecting on outcomesafter completing tasks
- ✔️Validating that requirementsare met
- 📝Documenting discoveriesand learnings
- 🎯Creating cognitive checkpointsyou can't skip

This helps the AI think step-by-step, improving accuracy and compliance.

- Node.js 18+ or Bun runtime
- npm or bun package manager

# Clone the repository git clone https://github.com/sterling/think-tool.git cd think-tool # Install dependencies bun install # or npm install # Run in development mode (with hot-reload) bun run dev # or npm run dev

# Build TypeScript to JavaScript bun run build # or npm run build # Run the built version bun start # or npm start

├── src/ │ └── server.ts # TypeScript source code ├── dist/ # Built JavaScript (generated) │ ├── server.js # Main server file │ └── cli.js # CLI executable ├── package.json # NPM package configuration └── tsconfig.json # TypeScript configuration

- PORT: Server port (default: 8080)

PORT=3000 npx mcp-reflection-tool

The reflection tool implements the Model Context Protocol (MCP) to provide a standardized way for AI assistants to access external tools. When an AI assistant needs to reflect on a problem:
- The AI calls thereflecttool with its reasoning
- The tool logs the thought process to the server console
- The tool acknowledges the checkpoint back to the AI
- This creates a cognitive checkpoint that improves reasoning quality

This "thinking out loud" effect has been shown to significantly improve the accuracy and completeness of AI responses.

# Use a different port PORT=8081 npx mcp-reflection-tool

# Reinstall globally with proper permissions sudo npm install -g mcp-reflection-tool

- Ensure the MCP server is running
- Restart your AI tool after adding configuration
- Check for valid JSON syntax in config files
- Verify the config file location for your OS

- Server logs: Visible in terminal where server is running
- Claude Code logs:~/Library/Logs/Claude/mcp*.log(macOS)
- VS Code logs: View > Output > Select "Cline" from dropdown
- Cursor logs: Help > Toggle Developer Tools > Console

# Check if package is installed globally npm list -g mcp-reflection-tool # Test the server directly npx mcp-reflection-tool # Test stdio mode echo '{"jsonrpc":"2.0","method":"initialize","id":1}' | npx mcp-reflection-tool

Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (git checkout -b feature/amazing-feature)
- Commit your changes (git commit -m 'Add amazing feature')
- Push to the branch (git push origin feature/amazing-feature)
- Open a Pull Request

MIT License - see the LICENSE file for details.

Created as an MCP implementation for enhancing AI reasoning capabilities.

- NPM Package
- GitHub Repository
- Model Context Protocol Docs
- Report Issues

- Built withFastMCPframework
- Implements theModel Context Protocolstandard
- Inspired by research on structured reasoning for AI systems

Persistent memory for any AI assistant. Zero token cost until recall. Stores memories in local SQLite, ranks by 6-factor scoring, returns results 79% smaller than JSON. Works with Claude, ChatGPT, Grok, Cursor, Windsurf, and any MCP client.