claude-gpt-collabration/README.md

MCP server for GPT-5 interactive file reading and collaboration with Claude Code

# @mcp/enhanced-gpt5

[![npm version](https://badge.fury.io/js/@mcp%2Fenhanced-gpt5.svg)](https://badge.fury.io/js/@mcp%2Fenhanced-gpt5)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

MCP server for GPT-5 interactive file reading and collaboration with Claude Code.

## Features

🤖 **GPT-5 Integration** - Direct access to OpenAI's GPT-5 API
📁 **File Collaboration** - GPT-5 can read and analyze project files
🔄 **Multi-turn Conversations** - Support for complex interactive workflows
🛠️ **Multiple Tools** - Various collaboration modes for different use cases

## Installation

```bash
npm install @mcp/enhanced-gpt5
```

## Prerequisites

- **Node.js**: Version 20 or higher
- **OpenAI API Key**: Access to GPT-5 models

## Configuration

### Environment Variables

Set your OpenAI API key:

```bash
export OPENAI_API_KEY=sk-your-api-key-here
```

Or create a `.env` file:

```env
OPENAI_API_KEY=sk-your-api-key-here
GPT5_DEBUG=false
NODE_ENV=production
```

### Claude Code Integration

Add to your Claude Code MCP configuration (`~/.claude/mcp_config.json`):

```json
{
  "mcpServers": {
    "enhanced-gpt5": {
      "command": "node",
      "args": ["node_modules/@mcp/enhanced-gpt5/build/index.js"],
      "env": {
        "OPENAI_API_KEY": "sk-your-api-key-here"
      }
    }
  }
}
```

Or use the command line:

```bash
claude mcp add enhanced-gpt5 "node node_modules/@mcp/enhanced-gpt5/build/index.js"
```

## Available Tools

### Core Tools

1. **echo** - Test connectivity and echo back text
2. **gpt5_generate** - Generate text using GPT-5 with customizable parameters
3. **gpt5_collaborate** - Collaborate with GPT-5 with file system access
4. **gpt5_collaborate_with_files** - Advanced file collaboration with proactive file uploads
5. **gpt5_collaborate_basic** - Basic collaboration using content injection

### Usage Examples

#### Basic Text Generation
```javascript
// In Claude Code
"Use the enhanced-gpt5 gpt5_generate tool to explain quantum computing"
```

#### File Collaboration
```javascript
// In Claude Code
"Use gpt5_collaborate to analyze this TypeScript project and suggest improvements"
```

#### Specific File Analysis
```javascript
// In Claude Code
"Use gpt5_collaborate_with_files to analyze the main index.ts file and explain its architecture"
```

## Tool Parameters

### gpt5_generate
- `input` (required): The prompt text
- `model`: GPT model variant (default: "gpt-5-chat-latest")
- `instructions`: System instructions
- `reasoning_effort`: "low" | "medium" | "high" (default: "medium")
- `max_output_tokens`: Maximum tokens to generate (default: 512)

### gpt5_collaborate
- `root` (required): Project root path
- `task` (required): What you want GPT-5 to do
- `model`: Model to use (default: "gpt-5")
- `instructions`: Additional system instructions
- `max_rounds`: Maximum collaboration rounds (default: 4)

## Development

### Building from Source

```bash
git clone <repository-url>
cd servers/enhanced-gpt5
npm install
npm run build
```

### Running Tests

```bash
npm test
```

### Debug Mode

Enable debug logging:

```env
GPT5_DEBUG=true
NODE_ENV=development
```

## Troubleshooting

### Common Issues

1. **Server won't start**: Check Node.js version (needs 20+)
2. **Authentication errors**: Verify your OpenAI API key is set correctly
3. **Tool not recognized**: Restart Claude Code after adding the MCP server

### Getting Help

- Check the [GitHub Issues](https://github.com/your-org/claude-gpt-collabration/issues)
- Review the debug logs when `GPT5_DEBUG=true`

## License

MIT © Enhanced MCP Framework

## Contributing

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

## Changelog

### 1.0.0
- Initial release
- GPT-5 text generation
- File collaboration tools
- Multi-turn conversation support
- MCP protocol compliance