openai-agents-sdk-mcp-server

OpenAI Agents SDK MCP Server

A comprehe## 📚 Documentation

📖 Setup & Usage Guide - Complete installation, configuration, and usage instructions

This guide covers everything you need:

• Quick installation and setup
• Configuration for all AI assistants (Cursor, Cline, Claude Desktop)
• Available tools and usage examples
• Troubleshooting common issues

📋 PrerequisitesCP (Model Context Protocol) server that provides access to the complete OpenAI Agents Python SDK documentation for AI coding assistants like Cursor, Cline, and Roo.

🎯 Overview

This MCP server enables AI coding assistants to access up-to-date OpenAI Agents SDK documentation, including:

• 15+ Documentation Sections: Complete coverage from quickstart to advanced topics
• API References: Detailed documentation for Agent, Runner, Tools, and Models
• Smart Search: Intelligent search with relevance scoring across all documentation
• Code Examples: Extraction and delivery of relevant code examples
• Intelligent Caching: 30-minute cache to minimize API calls while staying current

🚀 Features

📚 Complete Documentation Coverage

• Getting Started: Overview, Quickstart Guide
• Core Concepts: Agents, Running Agents, Tools, Handoffs, Guardrails
• Configuration: Models, SDK Configuration
• Advanced: Context Management
• Debugging & Monitoring: Tracing, Agent Visualization
• Integration: Model Context Protocol (MCP)
• Examples: Real-world implementation patterns
• API Reference: Complete API documentation for all classes

🔍 Smart Search Capabilities

• Keyword Search: Find relevant documentation sections
• Category Filtering: Filter by documentation category
• Relevance Scoring: Results ranked by relevance
• Multi-term Search: Handle complex queries effectively

💻 Code Example Extraction

• Targeted Examples: Get examples for specific topics
• Code Block Extraction: Automatically extract Python code blocks
• Topic Mapping: Intelligent mapping of topics to relevant sections

⚡ Performance Optimized

• Intelligent Caching: 30-minute TTL to balance freshness and performance
• Efficient Fetching: Only fetch content when requested
• Error Handling: Graceful degradation when content is unavailable

� Documentation

• Usage Guide - Detailed usage examples and integration instructions
• Configuration Guide - Complete setup instructions for all AI assistants
• Implementation Review - Technical deep dive and architecture overview

�📋 Prerequisites

• Node.js 18+
• npm or yarn

🛠 Installation & Quick Start

Option 1: Install from npm (Recommended)

# Install globally for easy access
npm install -g openai-agents-sdk-mcp-server

# Get your configuration
npx openai-agents-mcp-config

Option 2: Clone and Build

# Clone the repository
git clone https://github.com/kenneth-tao/openai-agents-sdk-mcp-server.git
cd openai-agents-sdk-mcp-server

# Install dependencies and build
npm install
npm run build

# Get your configuration
node get-config.js

Test the Installation

# Test the server (for global install)
openai-agents-mcp

# Or for local install
npm start

The server will start and display: OpenAI Agents Python MCP Server running on stdio

✅ Issues Fixed

The following TypeScript issues have been resolved:

• ✅ Type Safety: Added proper interfaces for DocumentationSection and DocumentationSections
• ✅ Object Indexing: Fixed unsafe object property access with proper type guards
• ✅ Argument Validation: Added proper type checking for tool arguments
• ✅ Error Handling: Improved error handling with proper type guards
• ✅ Resource Annotations: Fixed missing URL property in resource annotations
• ✅ Map Type Issues: Fixed category grouping with proper array-based Map structure

🔧 MCP Server Configuration

Resources Available

The server provides access to 15+ documentation resources:

Resource URI	Description	Category
openai-agents://docs/overview	SDK Overview and Introduction	Getting Started
openai-agents://docs/quickstart	Step-by-step Quickstart Guide	Getting Started
openai-agents://docs/agents	Agent Creation and Configuration	Core Concepts
openai-agents://docs/running-agents	Running Agents with Runner	Core Concepts
openai-agents://docs/tools	Function Tools and Hosted Tools	Core Concepts
openai-agents://docs/handoffs	Agent-to-Agent Delegation	Core Concepts
openai-agents://docs/guardrails	Input/Output Validation	Core Concepts
openai-agents://docs/models	Model Configuration	Configuration
openai-agents://docs/context	Context Management	Advanced
openai-agents://docs/tracing	Built-in Tracing	Debugging & Monitoring
openai-agents://docs/visualization	Agent Visualization	Debugging & Monitoring
openai-agents://docs/config	SDK Configuration	Configuration
openai-agents://docs/mcp	Model Context Protocol	Integration
openai-agents://docs/examples	Example Implementations	Examples
openai-agents://docs/api-*	API References	API Reference

Tools Available

🔍 search_documentation

Search across all OpenAI Agents SDK documentation.

Parameters:

• query (string, required): Search query
• category (string, optional): Filter by category

Categories:

• Getting Started, Core Concepts, Configuration, Advanced
• Debugging & Monitoring, Integration, Examples, API Reference

Example:

{
  "name": "search_documentation",
  "arguments": {
    "query": "function tools with validation",
    "category": "Core Concepts"
  }
}

📝 get_code_examples

Get code examples for specific SDK functionality.

Parameters:

• topic (string, required): Topic to get examples for

Supported Topics:

• basic agent, function tools, handoffs, guardrails
• tracing, models, context, mcp

Example:

{
  "name": "get_code_examples",
  "arguments": {
    "topic": "function tools"
  }
}

🔌 Integration with AI Assistants

Quick Configuration

After installation, get your configuration:

# Get configuration for your system
npx openai-agents-mcp-config

This will output the correct command and args for your installation type.

Cursor Configuration

Add to your Cursor settings (settings.json):

{
  "mcp.servers": {
    "openai-agents-sdk": {
      "command": "openai-agents-mcp",
      "args": [],
      "description": "OpenAI Agents SDK documentation",
      "disabled": false
    }
  }
}

Cline Configuration

Add to your Cline MCP settings:

{
  "mcpServers": {
    "openai-agents-sdk": {
      "command": "openai-agents-mcp",
      "args": [],
      "env": {},
      "disabled": false
    }
  }
}

Roo Configuration

Configure Roo to use this MCP server with the same command and arguments.

📖 For detailed configuration instructions for all AI assistants, see docs/CONFIGURATION.md

🎯 Usage Examples

Once configured with your AI assistant, you can ask questions like:

Basic Usage

• "How do I create a basic Agent with the OpenAI Agents SDK?"
• "Show me how to add function tools to an agent"
• "What's the syntax for running an agent?"

Advanced Features

• "How do I implement handoffs between agents?"
• "Show me how to set up guardrails for input validation"
• "How do I enable tracing for my agent workflow?"

API References

• "What are the parameters for the Agent class constructor?"
• "How do I configure the Runner class?"
• "What methods are available on the Tool class?"

📖 For more detailed examples and integration guides, see docs/USAGE.md

📁 Project Structure

├── src/
│   └── index.ts              # Main MCP server implementation
├── dist/                     # Compiled JavaScript files
├── docs/                     # Documentation
│   ├── USAGE.md             # Detailed usage guide
│   ├── CONFIGURATION.md     # Setup and configuration
│   └── IMPLEMENTATION_REVIEW.md # Technical architecture review
├── .vscode/
│   ├── launch.json          # Debug configuration
│   ├── tasks.json           # Build tasks
│   └── mcp.json             # MCP server configuration
├── .github/
│   └── copilot-instructions.md  # Copilot instructions
├── package.json             # Project configuration
├── tsconfig.json            # TypeScript configuration
├── README.md                # This file
└── test.js                  # Test script

🔧 Development

Build Commands

# Build the project
npm run build

# Start the server
npm start

# Development mode (auto-rebuild)
npm run dev

# Run tests
npm test

Debug in VS Code

1. Open the project in VS Code
2. Press F5 or go to Run & Debug
3. Select "Debug MCP Server"
4. The server will build automatically and start in debug mode

🤝 Contributing

This MCP server is designed to be robust and comprehensive. If you notice any issues or have suggestions for improvements, please feel free to contribute.

📄 License

MIT License

---

Ready to supercharge your AI coding assistant with OpenAI Agents SDK knowledge! 🚀