# MCP Servers Monorepo

A pnpm monorepo collection of MCP (Model Context Protocol) servers for integrating various AI models and services with Claude Desktop.

## 📦 Available Servers

### OpenAI GPT-5 Server
Integration with OpenAI's GPT-5 API with dual interface support for flexible AI interactions.

- **Package**: `@boseong/mcp-openai-gpt5`
- **Features**: Dual tools (simple + messages), enhanced token reporting, flexible environment
- **[Documentation](./packages/gpt5-server/README.md)**

### Future Servers (Planned)
- **Anthropic Server**: Direct integration with Claude API
- **Google Gemini Server**: Integration with Google's Gemini models
- **Local LLM Server**: Support for local language models
- **Database Query Server**: SQL and NoSQL database interactions
- **Web Scraping Server**: Advanced web content extraction

## 🚀 Quick Start

### Prerequisites
- Node.js >= 18.0.0
- pnpm >= 10.0.0 (for development)
- Claude Desktop application

**Note**: If you have an older version of pnpm, upgrade with:
```bash
pnpm add -g pnpm@latest
```

### Installation

Each server can be installed independently via npm:

```bash
# Install OpenAI GPT-5 server
npm install -g @boseong/mcp-openai-gpt5
```

Or use directly with npx (no installation required):

```bash
npx @boseong/mcp-openai-gpt5
```

### Configuration

1. **Set up environment variables**:
   ```bash
   cp .env.example .env
   # Edit .env with your API keys
   ```

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

   ```json
   {
     "mcpServers": {
       "gpt5": {
         "command": "npx",
         "args": ["@boseong/mcp-openai-gpt5"],
         "env": {
           "OPENAI_API_KEY": "your-api-key"
         }
       }
     }
   }
   ```

   **Note**: You can use either `"gpt5"` or `"openai-gpt5"` as the server key name. Using `"gpt5"` is recommended for easier invocation in Claude Code.

## 🛠️ Development

### Monorepo Structure

```
mcp-servers/
├── packages/                  # All MCP server packages
│   ├── gpt5-server/          # GPT-5 MCP server
│   │   ├── src/              # TypeScript source
│   │   ├── dist/             # Compiled JavaScript (git-ignored)
│   │   ├── package.json      # Package configuration
│   │   └── README.md         # Server documentation
│   └── [other-servers]/      # Future MCP servers
├── .env.example              # Environment variables template
├── pnpm-workspace.yaml       # pnpm workspace configuration
├── tsconfig.json             # Root TypeScript configuration
├── package.json              # Root package.json with workspace scripts
├── .gitignore                # Git ignore rules
├── CLAUDE.md                 # Claude Code guidance
└── README.md                 # This file
```

### Creating a New MCP Server

1. Create a new directory under `packages/`:
   ```bash
   mkdir packages/your-server-name
   cd packages/your-server-name
   pnpm init
   ```

2. Install MCP SDK:
   ```bash
   pnpm add @modelcontextprotocol/sdk
   ```

3. Follow the structure of existing servers for implementation

4. Add TypeScript support:
   ```bash
   pnpm add -D typescript @types/node
   ```

5. Configure build process and create your MCP server implementation

6. Add your package to the root tsconfig.json references

### Building from Source

```bash
# Clone the repository
git clone https://github.com/boseong/mcp-servers.git
cd mcp-servers

# Install all dependencies using pnpm
pnpm install

# Build all packages
pnpm build

# Build a specific server
pnpm --filter gpt5-server build
```

### Development Workflow

```bash
# Install dependencies for all packages
pnpm install

# Run development mode for all packages
pnpm dev

# Run development for specific package
pnpm --filter gpt5-server dev

# Build all packages
pnpm build

# Test all packages
pnpm test

# Clean all build artifacts
pnpm clean
```

## 📝 Contributing

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

### Guidelines
1. Follow the existing code structure and patterns
2. Add comprehensive documentation
3. Include TypeScript types
4. Test thoroughly before submitting
5. Update this README when adding new servers

## 📄 License

Each server may have its own license. Check the individual server directories for specific license information.

- GPT-5 Server: MIT License

## 🔗 Resources

- [Model Context Protocol Documentation](https://modelcontextprotocol.io)
- [Claude Desktop](https://claude.ai)
- [MCP SDK](https://github.com/modelcontextprotocol/sdk)

## 💬 Support

For issues and questions:
- Create an issue in the GitHub repository
- Check individual server documentation
- Refer to the MCP documentation

## 🚧 Roadmap

- [x] Migrate to pnpm monorepo structure
- [ ] Add more AI model integrations
- [ ] Create utility servers (database, file system, etc.)
- [ ] Develop testing framework for MCP servers
- [ ] Add server templates for quick development
- [ ] Create automated publishing workflow with changesets

---

**Note**: This is an active development repository. New servers and features are being added regularly.