@whyuds/coding-converse/README.md

An MCP server that enables interactive conversations between AI code editors and users for collaborative problem-solving

# CodingConverse

🤖 An MCP (Model Context Protocol) server that enables interactive conversations between AI code editors and users for collaborative problem-solving.

## Overview

CodingConverse allows AI code editors like Cursor, Windsurf, and Trae to engage in real-time conversations with users when they encounter complex problems or need clarification during code generation. Instead of making assumptions or getting stuck, the AI can ask for user input and guidance.

## Features

- 🗣️ **Interactive Conversations**: AI editors can ask users questions and wait for responses
- 🖥️ **Terminal Interface**: Beautiful terminal UI with colored output and user-friendly prompts
- 📝 **Multiple Input Methods**: Support for both quick selections and detailed text input
- 💾 **Conversation History**: Track and export conversation sessions
- 🌍 **Cross-Platform**: Works on Windows, macOS, and Linux
- 📦 **Easy Integration**: Simple NPM package installation

## Installation

```bash
npm install -g @whyuds/coding-converse
```

## Usage

### Integration with AI Code Editors

Add CodingConverse to your AI editor's MCP configuration:

#### Cursor
```json
{
  "mcpServers": {
    "coding-converse": {
      "command": "npx",
      "args": [
        "-y",
        "@whyuds/coding-converse"
      ],
      "env": {}
    }
  }
}
```

#### Windsurf
```json
{
  "mcpServers": {
    "coding-converse": {
      "command": "npx",
      "args": [
        "-y",
        "@whyuds/coding-converse"
      ],
      "env": {}
    }
  }
}
```

#### Trae AI
```json
{
  "mcpServers": {
    "coding-converse": {
      "command": "npx",
      "args": [
        "-y",
        "@whyuds/coding-converse"
      ],
      "env": {}
    }
  }
}
```

### Available Tools

Once integrated, your AI editor will have access to these tools:

#### `ask_user`
Ask the user a question and wait for their response.

**Parameters:**
- `question` (required): The question to ask the user
- `context` (optional): Additional context about the current situation
- `options` (optional): Suggested response options for quick selection

**Example:**
```typescript
// AI editor can call this when stuck
ask_user({
  question: "Should I use TypeScript or JavaScript for this React component?",
  context: "I'm creating a form component that will handle user authentication. The project already has some TypeScript files.",
  options: ["TypeScript", "JavaScript", "Let me decide based on the existing codebase"]
})
```

#### `start_conversation`
Start a new conversation session with the user.

**Parameters:**
- `topic` (required): The topic or problem to discuss

#### `end_conversation`
End the current conversation session.

**Parameters:**
- `summary` (required): Summary of the conversation and decisions made

## How It Works

1. **AI Editor Integration**: Your AI code editor loads CodingConverse as an MCP server
2. **Problem Detection**: When the AI encounters a complex problem or needs clarification, it calls the `ask_user` tool
3. **Terminal Interface**: A beautiful terminal interface appears with the AI's question
4. **User Response**: You provide input through the terminal (either by selecting options or typing a custom response)
5. **Continuation**: The AI receives your response and continues with the improved context
6. **Conversation Tracking**: All exchanges are tracked and can be exported for future reference

## Example Scenarios

### Scenario 1: Architecture Decision
```
🤖 AI Editor asks:
I need to implement user authentication. Should I use JWT tokens, session-based auth, or OAuth integration?

Context: This is a Node.js Express app that will have both web and mobile clients.

Options:
1. JWT tokens
2. Session-based authentication
3. OAuth integration (Google, GitHub)
4. Other (type custom response)

> Your choice: 1
```

### Scenario 2: Error Resolution
```
🤖 AI Editor asks:
I'm getting a TypeScript error: "Property 'user' does not exist on type 'Request'". How should I handle this?

Context: I'm trying to access user data from a JWT token in an Express middleware.

Options:
1. Extend the Request interface
2. Use type assertion
3. Create a custom middleware type
4. Other (type custom response)

> Your choice: 1
```

### Scenario 3: Custom Implementation
```
🤖 AI Editor asks:
I need to implement real-time notifications. What approach would you prefer?

> Your response: I'd like to use WebSockets with Socket.io, but make sure it's scalable for multiple server instances. Please implement Redis adapter for clustering.
```

## Development

### Prerequisites
- Node.js 18+
- npm or yarn

### Setup
```bash
git clone https://github.com/whyuds/CodingConverse.git
cd CodingConverse
npm install
```

### Build
```bash
npm run build
```

### Development Mode
```bash
npm run dev
```

### Testing
```bash
npm test
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT License - see the [LICENSE](LICENSE) file for details.

## Support

If you encounter any issues or have questions:

1. Check the [Issues](https://github.com/whyuds/CodingConverse/issues) page
2. Create a new issue if your problem isn't already reported
3. Provide detailed information about your setup and the problem

## Roadmap

- [ ] Web-based interface option
- [ ] Conversation templates
- [ ] Integration with more AI editors
- [ ] Plugin system for custom conversation flows
- [ ] Voice input support
- [ ] Conversation analytics and insights

---

**Made with ❤️ for the AI coding community**