# OpenAI Agents MCP 🤖

[![npm version](https://badge.fury.io/js/openai-agents-mcp.svg)](https://www.npmjs.com/package/openai-agents-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A Model Context Protocol (MCP) server that bridges OpenAI's Agents SDK with Claude Code and other MCP clients. Enable powerful AI agent capabilities including web search, file search, and computer use directly in your development environment.

## 🚀 Quick Start

```bash
npx openai-agents-mcp
```

That's it! The server will start and be ready to accept MCP connections.

## 🎯 Features

- **🔍 Web Search** - Search the web using OpenAI's integrated web search capability
- **📁 File Search** - Analyze and search through files with AI-powered understanding
- **💻 Computer Use** - Interact with computer interfaces (preview feature, requires tier 3-5)
- **⚡ Real-time Streaming** - Stream responses for better user experience
- **🔧 Claude Code Ready** - Works seamlessly with Claude Code via stdio transport
- **🧪 Test-Driven** - Comprehensive test suite with high coverage
- **📦 NPX Compatible** - Run directly without installation

## 📋 Prerequisites

- Node.js 18.0.0 or higher
- OpenAI API key
- For computer use: OpenAI usage tier 3-5

## 🔧 Installation & Setup

### Option 1: NPX (Recommended)

No installation needed! Just run:

```bash
npx openai-agents-mcp
```

### Option 2: Global Installation

```bash
npm install -g openai-agents-mcp
openai-agents-mcp
```

### Option 3: From Source

```bash
git clone https://github.com/merlinrabens/openai-agents-mcp.git
cd openai-agents-mcp
npm install
npm run build
npm start
```

## ⚙️ Configuration

### Environment Variables

Create a `.env` file in your project root:

```env
# Required
OPENAI_API_KEY=sk-...your-key-here

# Optional
OPENAI_ORGANIZATION=org-...         # Your org ID
ENABLE_COMPUTER_USE=true            # Enable computer use (requires tier 3-5)
LOG_LEVEL=info                      # debug | info | warn | error
```

### Claude Code Integration

Add to your Claude Code configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "openai-agents": {
      "command": "npx",
      "args": ["openai-agents-mcp"],
      "env": {
        "OPENAI_API_KEY": "sk-...your-key-here"
      }
    }
  }
}
```

Then restart Claude Code to activate the server.

## 💡 Usage Examples

Once configured, you can use these commands in Claude Code:

### Web Search
```
Use the web_search tool to find the latest news about AI developments
```

### File Search
```
Use the file_search tool to analyze this codebase and find all API endpoints
```

### Computer Use (if enabled)
```
Use the computer_use tool to take a screenshot of the current screen
```

## 🏗️ Architecture

```
┌─────────────┐     MCP Protocol     ┌──────────────┐     OpenAI API     ┌──────────┐
│ Claude Code │ ◄──────────────────► │  This Server │ ◄─────────────────► │  OpenAI  │
│   or other  │      stdio/HTTP       │              │    Agents SDK       │  Agents  │
│ MCP Client  │                       │              │                     │          │
└─────────────┘                       └──────────────┘                     └──────────┘
```

### Key Components

- **MCP Server Core** - Handles MCP protocol using `@modelcontextprotocol/sdk`
- **OpenAI Integration** - Uses `@openai/agents` SDK for agent capabilities
- **Tool Translation** - Maps MCP tool calls to OpenAI function calls
- **Stream Handler** - Manages real-time streaming responses
- **Error Handler** - Provides retry logic and graceful error handling

## 🧪 Development

### Setup Development Environment

```bash
# Clone the repository
git clone https://github.com/merlinrabens/openai-agents-mcp.git
cd openai-agents-mcp

# Install dependencies
npm install

# Run in development mode
npm run dev
```

### Available Scripts

```bash
npm run dev          # Development mode with hot reload
npm test            # Run test suite
npm run test:watch  # Run tests in watch mode
npm run test:coverage # Generate coverage report
npm run build       # Build for production
npm run lint        # Run ESLint
npm run format      # Format with Prettier
```

### Project Structure

```
src/
├── server/         # MCP server implementation
│   └── index.ts    # Main server class
├── openai/         # OpenAI Agents SDK integration
│   └── client.ts   # OpenAI client wrapper
├── tools/          # Tool definitions
├── config/         # Configuration management
└── utils/          # Utilities and helpers

tests/              # Test suite
bin/               # CLI entry point
examples/          # Usage examples
```

## 📊 Testing

The project follows Test-Driven Development (TDD) principles:

```bash
# Run all tests
npm test

# Watch mode for development
npm run test:watch

# Coverage report
npm run test:coverage
```

Current test coverage: ~71%

## 💰 Pricing

This server uses OpenAI's API, which has the following pricing (as of March 2025):
- **Input**: $3 per 1M tokens
- **Output**: $12 per 1M tokens
- **Computer Use**: Research preview (requires tier 3-5)

## 🤝 Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Write tests first (TDD approach)
4. Implement your feature
5. Ensure all tests pass
6. Commit your changes (`git commit -m 'Add amazing feature'`)
7. Push to the branch (`git push origin feature/amazing-feature`)
8. Open a Pull Request

## 📝 License

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

## 🙏 Acknowledgments

Built with:
- [Model Context Protocol SDK](https://github.com/modelcontextprotocol/sdk) - The MCP protocol implementation
- [OpenAI Agents SDK](https://github.com/openai/openai-agents-js) - OpenAI's agent framework
- [Claude Code](https://claude.ai/code) - Anthropic's AI-powered development environment

## 🐛 Troubleshooting

### Server won't start
- Ensure `OPENAI_API_KEY` is set correctly
- Check Node.js version is 18.0.0 or higher
- Run `npm run build` if running from source

### Claude Code doesn't see the server
- Restart Claude Code after updating configuration
- Check the configuration file path is correct
- Verify the server starts without errors: `npx openai-agents-mcp`

### Computer use not working
- Verify your OpenAI account is tier 3-5
- Set `ENABLE_COMPUTER_USE=true` in environment

## 📧 Support

- **Issues**: [GitHub Issues](https://github.com/merlinrabens/openai-agents-mcp/issues)
- **Discussions**: [GitHub Discussions](https://github.com/merlinrabens/openai-agents-mcp/discussions)
- **Author**: Merlin Rabens

## 🚦 Status

- ✅ Web Search - Fully functional
- ✅ File Search - Fully functional
- ⚠️ Computer Use - Preview (requires tier 3-5)
- 🚧 OpenAI Agents SDK - Preview as of March 2025

---

**Note**: The OpenAI Agents SDK is currently in preview. Features and pricing may change. The deprecated Assistants API will be sunset by mid-2026 in favor of the Agents SDK.