jezweb-mcp-core

v4.0.0

Published

7 months ago

Jezweb Model Context Protocol (MCP) Core - A universal server for providing AI tools and resources, designed for seamless integration with various AI models and clients. Features adaptable multi-provider support, comprehensive tool and resource management

Universal OpenAI Assistants MCP Server (NPM Package)

A Model Context Protocol (MCP) server that provides comprehensive OpenAI Assistants API operations through stdio transport. This is the recommended installation method for most users, offering direct compatibility with Claude Desktop, Roo, and other MCP clients without requiring proxy servers.

🆕 Complete Assistants API Coverage: Now includes all 22 Assistants API tools for complete assistant, thread, message, and run management.

🌟 Part of the Universal MCP Server Ecosystem

This NPM package is one of three deployment options for the Universal OpenAI Assistants MCP Server:

📦 NPM Package (This package) - Direct stdio transport, no proxy required
☁️ Cloudflare Workers - Zero-setup cloud deployment
🔧 Local Development - Full source code access and customization

Choose the option that best fits your needs. See the main repository for all options.

✨ Enhanced Features

🚀 Core Capabilities

22 Comprehensive Tools: Complete OpenAI Assistants API coverage with enhanced descriptions
Assistant Management: Create, update, list, and delete assistants with template support
Thread Management: Full conversation thread lifecycle management
Message Management: Create, list, update, and delete messages
Run Management: Execute assistant runs with tool output support
Run Step Management: Monitor and inspect run execution steps

🎯 Enhanced User Experience

9 MCP Resources: Templates, workflows, and comprehensive documentation
Enhanced Tool Descriptions: Workflow-oriented descriptions with practical examples
Improved Validation: Context-aware error messages with actionable guidance
Tool Annotations: Proper MCP annotations (readOnly, destructive, idempotent)
Assistant Templates: Pre-configured templates for coding, writing, data analysis, and support

🔧 Technical Excellence

Direct Stdio Transport: No proxy servers required - fastest and most reliable
Universal Compatibility: Works with Claude Desktop, Roo, and all MCP clients
TypeScript: Full type safety and modern development experience
Zero Dependencies: Lightweight with minimal runtime footprint
Easy Installation: Simple npx usage or global installation
Comprehensive Testing: Enhanced test suite validating all improvements
Environment Variable Support: Secure API key management

🛠️ Enhanced Tools (22 Total)

All tools now feature enhanced descriptions with workflow context, practical examples, and usage guidance.

📚 MCP Resources (9 Total)

🤖 Assistant Templates (4 resources)

Coding Assistant - Code review, debugging, and programming help
Writing Assistant - Content creation, editing, and proofreading
Data Analyst - Data analysis, visualization, and statistical insights
Customer Support - Customer service and support ticket handling

🔄 Workflow Examples (2 resources)

Create and Run Workflow - Complete step-by-step assistant setup
Batch Processing Workflow - Efficient multi-task processing patterns

📖 Documentation (3 resources)

API Reference - ID formats, parameters, and specifications
Error Handling Guide - Common errors and debugging techniques
Best Practices Guide - Performance, security, and optimization

🛠️ Available Tools (22 Total)

Assistant Management (5 tools)

assistant-create - Create a new OpenAI assistant with specified instructions and tools
assistant-list - List all assistants with optional pagination and filtering
assistant-get - Retrieve details of a specific assistant
assistant-update - Update an existing assistant
assistant-delete - Delete an assistant permanently

Thread Management (4 tools)

thread-create - Create a new conversation thread
thread-get - Retrieve details of a specific thread
thread-update - Update an existing thread
thread-delete - Delete a thread permanently

Message Management (5 tools)

message-create - Add a message to a thread
message-list - List messages in a thread with optional pagination
message-get - Retrieve details of a specific message
message-update - Update an existing message
message-delete - Delete a message from a thread

Run Management (6 tools)

run-create - Start a new assistant run on a thread
run-list - List runs for a thread with optional pagination
run-get - Retrieve details of a specific run
run-update - Update an existing run
run-cancel - Cancel a running assistant execution
run-submit-tool-outputs - Submit tool call results to continue a run

Run Step Management (2 tools)

run-step-list - List steps in a run execution
run-step-get - Get details of a specific run step

Installation

Option 1: NPX (Recommended)

npx openai-assistants-mcp@latest

Option 2: Global Installation

npm install -g openai-assistants-mcp@latest
openai-assistants-mcp

Option 3: Local Installation

npm install openai-assistants-mcp@latest
npx openai-assistants-mcp@latest

💡 Why use @latest?

Ensures you get the most recent bug fixes and improvements
Bypasses NPM cache issues that can cause outdated versions
Recommended for most reliable experience

Prerequisites

Node.js: Version 18.0.0 or higher
OpenAI API Key: Required for Assistants API operations (configured via MCP client)

Configuration

API Key Setup

Important: As of version 1.0.0, this package no longer requires environment variables to be set before startup. The API key is provided by your MCP client configuration and validated only when tools are called.

The server will start successfully without an API key and will only validate it when you actually use the assistants tools.

🔧 Client Integration

Claude Desktop Setup

Add the following configuration to your Claude Desktop settings:

macOS

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "openai-assistants": {
      "command": "npx",
      "args": ["openai-assistants-mcp@latest"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key-here"
      }
    }
  }
}

Windows

Edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "openai-assistants": {
      "command": "npx",
      "args": ["openai-assistants-mcp@latest"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key-here"
      }
    }
  }
}

Linux

Edit ~/.config/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "openai-assistants": {
      "command": "npx",
      "args": ["openai-assistants-mcp"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key-here"
      }
    }
  }
}

🤖 Roo Integration

Roo users get the best experience with this NPM package due to direct stdio transport. Add the following to your Roo configuration:

Roo Configuration

Edit your Roo configuration file (typically ~/.config/roo/config.json):

{
  "mcpServers": {
    "openai-assistants": {
      "command": "npx",
      "args": ["openai-assistants-mcp@latest"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key-here"
      },
      "alwaysAllow": [
        "assistant-create",
        "assistant-list",
        "assistant-get",
        "assistant-update",
        "assistant-delete",
        "thread-create",
        "thread-get",
        "thread-update",
        "thread-delete",
        "message-create",
        "message-list",
        "message-get",
        "message-update",
        "message-delete",
        "run-create",
        "run-list",
        "run-get",
        "run-update",
        "run-cancel",
        "run-submit-tool-outputs",
        "run-step-list",
        "run-step-get"
      ]
    }
  }
}

Why Roo Users Should Choose This Package

No Proxy Required: Direct stdio communication is faster and more reliable
Automatic Tool Approval: The alwaysAllow configuration prevents constant permission prompts
Better Performance: No HTTP overhead or network latency
Simpler Setup: No need to install or manage mcp-proxy
Local Execution: Full control over the server environment

Roo-Specific Features

Seamless Integration: Works out-of-the-box with Roo's MCP implementation
Tool Auto-Approval: Pre-configure all 22 tools to avoid interruptions
Environment Variables: Secure API key management through environment variables
Debug Support: Easy debugging with DEBUG=* environment variable

🖥️ Claude Code CLI Integration

Claude Code CLI users get excellent performance with this NPM package due to direct stdio transport. Add the MCP server using the command line interface:

Basic Setup

# Add the MCP server with local scope (default - available only in current project)
claude mcp add openai-assistants -- npx openai-assistants-mcp@latest --env OPENAI_API_KEY="your-openai-api-key-here"

# Add with project scope (shared with team via .mcp.json file)
claude mcp add --scope project openai-assistants -- npx openai-assistants-mcp@latest --env OPENAI_API_KEY="your-openai-api-key-here"

# Add with user scope (available across all your projects)
claude mcp add --scope user openai-assistants -- npx openai-assistants-mcp@latest --env OPENAI_API_KEY="your-openai-api-key-here"

Scope Options

--scope local (default): Available only to you in the current project
--scope project: Shared with everyone in the project via .mcp.json file
--scope user: Available to you across all projects

Managing MCP Servers

# List all configured servers
claude mcp list

# Get details for the server
claude mcp get openai-assistants

# Remove the server
claude mcp remove openai-assistants

# Check server status within Claude Code
/mcp

Project-Level Configuration (.mcp.json)

When using --scope project, Claude Code creates a .mcp.json file in your project root:

{
  "mcpServers": {
    "openai-assistants": {
      "command": "npx",
      "args": ["openai-assistants-mcp@latest"],
      "env": {
        "OPENAI_API_KEY": "${OPENAI_API_KEY}"
      }
    }
  }
}

Environment Variable Expansion: Claude Code supports ${VAR} syntax for environment variables in .mcp.json files.

Why Claude Code CLI Users Should Choose This Package

Direct Stdio Transport: Fastest possible communication with no HTTP overhead
Command-Line Management: Easy server management with claude mcp commands
Flexible Scoping: Choose between local, project, or user-level configurations
Environment Variable Support: Secure API key management through environment variables
Team Collaboration: Share configurations via .mcp.json files

📖 Enhanced Usage Examples

Using MCP Resources

Access Assistant Templates

# Get a pre-configured template
"Show me the coding assistant template"
"Use the data analyst template to create a new assistant"
"What tools does the customer support template include?"

Follow Workflow Examples

# Get step-by-step guidance
"Show me the complete create and run workflow"
"How do I implement batch processing?"
"Walk me through the assistant creation process"

Access Documentation

# Get comprehensive guidance
"Show me the best practices guide"
"What are common error handling patterns?"
"Display the API reference documentation"

Complete Assistant Workflow

Template-Based Assistant Creation

# 1. Access a template (via MCP client)
"Show me the coding assistant template"

# 2. Create assistant using template guidance
"Create an assistant named 'Code Helper' using gpt-4 with code interpreter and file search tools"

# 3. Create a conversation thread
"Create a new thread for discussing Python programming"

# 4. Add a message to the thread
"Add a user message to the thread asking 'How do I create a list comprehension?'"

# 5. Run the assistant on the thread
"Start a run with the Code Helper assistant on this thread"

# 6. Monitor the run progress
"Get the status of the current run"

# 7. List all messages in the thread to see the response
"List all messages in this thread"

Advanced Assistant Management

# Create a specialized assistant
"Create an assistant named 'Data Analyst' using gpt-4 with file search and code interpreter tools"

# Update assistant instructions
"Update the Data Analyst assistant with new instructions about handling CSV files"

# List all your assistants
"Show me all my assistants"

# Get detailed information about an assistant
"Get details about the Data Analyst assistant"

Thread and Message Management

# Create a thread with initial messages
"Create a thread with an initial user message asking about machine learning"

# Add multiple messages to a conversation
"Add an assistant message explaining neural networks to the thread"
"Add a user follow-up question about training data"

# Update message metadata
"Update the metadata for the last message to mark it as important"

# List messages with filtering
"List the last 10 messages in this thread"
"List messages from a specific run"

Run Management and Tool Outputs

# Start a run with custom instructions
"Start a run with additional instructions to focus on Python examples"

# Monitor run execution
"List all runs for this thread"
"Get details about the current run including any required actions"

# Handle tool calls (when assistant needs external tools)
"Submit tool outputs for the function calls in the current run"

# Cancel a long-running execution
"Cancel the current run if it's taking too long"

Run Step Inspection

# Monitor detailed execution steps
"List all steps in the current run to see what the assistant is doing"

# Get specific step details
"Get details about step 3 in the current run"

# Debug assistant behavior
"Show me all the steps to understand how the assistant processed my request"

Testing

Run the built-in test suite to verify the server is working correctly:

cd npm-package
npm test

The test suite validates:

Server initialization
Tool listing (all 22 tools)
Protocol compliance
Error handling

Development

Building from Source

Clone the repository
Install dependencies:
```
npm install
```
Build the TypeScript code:
```
npm run build
```
Run tests:
```
npm test
```

Project Structure

npm-package/
├── src/
│   ├── index.ts           # Main server entry point
│   ├── mcp-handler.ts     # MCP protocol handler
│   ├── openai-service.ts  # OpenAI API service
│   └── types.ts           # TypeScript type definitions
├── bin/
│   └── openai-assistants-mcp.js  # Executable script
├── dist/                  # Compiled JavaScript output
├── test/
│   └── test-stdio.js      # Test suite
└── package.json

🔍 Enhanced Error Handling

The server includes comprehensive enhanced error handling:

Enhanced Error Messages

Context-Aware Errors: Detailed error messages with specific guidance
Format Examples: Show exactly what valid input looks like
Documentation References: Link to relevant guides and specifications
Actionable Guidance: Clear steps to resolve issues

Error Categories

Invalid API Key: Clear error message with setup instructions
Network Issues: Automatic retry logic for transient failures
Invalid Parameters: Enhanced validation with examples and suggestions
OpenAI API Errors: Proper error code mapping and user-friendly messages
Parameter Relationships: Validation of tool/resource consistency

Example Enhanced Error

Invalid assistant ID format for parameter 'assistant_id'.
Expected 'asst_' followed by 24 characters (e.g., 'asst_abc123def456ghi789jkl012'),
but received: 'invalid-id'.
See docs://openai-assistants-api for ID format specifications.

🛠️ Troubleshooting

Common Issues

1. "OPENAI_API_KEY environment variable is required" (when calling tools)

Solution: This error now only appears when you try to use tools without configuring the API key in your MCP client. The server will start successfully without an API key.

Configure your API key in your MCP client configuration (see Client Integration section above).

2. "Failed to start server" or "Command not found"

Solutions:

# Verify Node.js version (requires 18+)
node --version

# Update Node.js if needed (using nvm)
nvm install 18
nvm use 18

# Clear npm cache and reinstall
npm cache clean --force
npm install -g openai-assistants-mcp

# Test direct execution
npx openai-assistants-mcp --version

3. "Connection timeout" or "Network errors"