ken-you-think/README.md

A single-tool MCP that guides coding agents through implementation thinking - TypeScript edition

# Ken-You-Think MCP - TypeScript Edition 🚀

A metacognitive MCP server for vibe coding - gives coding agents thinking superpowers through a single, powerful tool.

**Version 3.0: Pure TypeScript, Zero Python Dependencies!**

## What's New in v3.0?

- **No Python Required** - Built with the official `@modelcontextprotocol/sdk`
- **No pip, No UV, No Permission Issues** - Just `npm install` and go
- **Works Everywhere** - If Node.js runs, Ken-You-Think runs
- **Same Powerful Thinking Tool** - All the metacognitive features you love

## Installation

### One-Line Install (Claude Code)
```bash
claude mcp add ken-you-think -s user -- npx -y ken-you-think@3
```

That's it! No Python setup, no permission errors, just works.

### Claude Desktop
Add to your configuration file:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "ken-you-think": {
      "command": "npx",
      "args": ["-y", "ken-you-think@3"]
    }
  }
}
```

## Key Features

- **Single Tool Architecture**: Just one `think` tool that does everything
- **Rich Thought Content**: Each thought contains detailed implementation insights
- **No Synthesis Step**: The final thought IS your implementation plan
- **Coding-Focused**: Tailored specifically for software implementation thinking
- **Minimal Parameters**: Only 5 essential parameters vs 13+ in other MCPs

## Usage

The MCP provides a single `think` tool with these parameters:

- `thought` (required): Your current thinking content (should be rich and detailed)
- `thoughtNumber` (required): Current thought number (1, 2, 3...)
- `totalThoughts` (required): Total thoughts planned for this problem
- `isInvestigating` (optional): Set to true when researching/investigating
- `investigationArea` (optional): What you're investigating
- `branchReason` (optional): Reason for branching to alternative approach
- `confidence` (optional): Your confidence level (0.0-1.0)

## Example Flow

```typescript
// First thought - Understanding
think({
  thought: "Understanding dark mode toggle request. Need: UI component, theme state management, CSS architecture, persistence mechanism.",
  thoughtNumber: 1,
  totalThoughts: 3,
  isInvestigating: true,
  investigationArea: "existing UI patterns"
})

// Middle thought - Investigation results
think({
  thought: "Found: React Context for state, CSS variables for theming, localStorage for persistence. Will create ThemeContext with useTheme hook.",
  thoughtNumber: 2,
  totalThoughts: 3,
  confidence: 0.95
})

// Final thought - Implementation plan
think({
  thought: `Implementation plan:
    1. Create contexts/ThemeContext.jsx with ThemeProvider and useTheme hook
    2. Build components/ui/ThemeToggle.jsx using existing Button component  
    3. Add CSS variables to :root for --bg-color, --text-color
    4. Integrate: Wrap App in ThemeProvider, add toggle to Header
    5. Test: Verify persistence, smooth transitions, existing component compatibility`,
  thoughtNumber: 3,
  totalThoughts: 3
})
```

## Resources

The MCP also provides resources for introspection:
- `thinking://current` - View current thinking session
- `thinking://history` - See all thoughts from current session

## Development

To modify or extend Ken-You-Think:

1. Clone the repository
2. Install dependencies: `npm install`
3. Make changes in `src/index.ts`
4. Build: `npm run build`
5. Test: `npm start`

### Development with hot reload:
```bash
npm run dev
```

## Why TypeScript?

After struggling with Python dependency hell (pip permissions on Mac, UV installation issues, version conflicts), we rebuilt Ken-You-Think in pure TypeScript using the official MCP SDK. The result:

- **Zero installation issues** - NPM just works
- **Cross-platform by default** - Node.js handles everything
- **Better developer experience** - TypeScript types, modern tooling
- **Simpler distribution** - One `npx` command, done

## Philosophy

Ken-You-Think believes that:
1. **Thinking is the content**, not the prompts
2. **One tool is enough** when it's well-designed
3. **Implementation details** should emerge through thinking
4. **The final thought** should be immediately actionable
5. **Simplicity** enables more powerful thinking

## Migration from Python Version

If you're upgrading from v2.x (Python):
1. Remove the old version: `claude mcp remove ken-you-think`
2. Install the new version: `claude mcp add ken-you-think -s user -- npx -y ken-you-think@3`
3. Restart Claude

The thinking interface remains exactly the same - only the underlying implementation has changed.

## License

MIT License - See LICENSE file for details.

---

*Built with frustration about Python dependencies and love for simple solutions.*