@agentics.org/agentic-mcp
Version:
Agentic MCP Server with advanced AI capabilities including web search, summarization, database querying, and customer support. Built by the Agentics Foundation to enhance AI agents with powerful tools for research, content generation, and data analysis.
294 lines (235 loc) • 9.73 kB
Markdown
# @agentics.org/agentic-mcp
[](https://www.npmjs.com/package/@agentics.org/agentic-mcp)
[](https://github.com/agenticsorg/edge-agents/tree/main/scripts/agentic-mcp)
# ♾️ Agentic MCP
A powerful Model Context Protocol server with advanced AI capabilities by the Agentics Foundation. Built on the OpenAI Agents API/SDK using TypeScript, this package implements a comprehensive MCP server that enhances AI agents with sophisticated tools and orchestration capabilities:
## 🌟 Core Capabilities
- **🔍 Web Search Research**: Generate comprehensive reports with up-to-date information from the web using `gpt-4o-search-preview`
- **📝 Smart Summarization**: Create concise, well-structured summaries with key points and citations
- **🗄️ Database Integration**: Query and analyze data from Supabase databases with structured results
- **👥 Customer Support**: Handle inquiries and provide assistance with natural language understanding
- **🔄 Agent Orchestration**: Seamlessly transfer control between specialized agents based on query needs
- **🔀 Multi-Agent Workflows**: Create complex agent networks with parent-child relationships and shared context
- **🧠 Context Management**: Sophisticated state tracking with memory, resources, and workflow management
- **🛡️ Guardrails System**: Configurable input and output validation to ensure safe and appropriate responses
- **📊 Tracing & Debugging**: Comprehensive logging and debugging capabilities for development
- **🔌 Edge Function Deployment**: Ready for deployment as Supabase Edge Functions
- **🔄 Streaming Support**: Real-time streaming responses for interactive applications
## 🚀 Installation
```bash
# Install globally
npm install -g @agentics.org/agentic-mcp
# Or as a project dependency
npm install @agentics.org/agentic-mcp
```
## 🏗️ Architecture
The Agentic MCP server is built on a modular architecture that enables seamless integration between AI agents and external tools:
### Core Components
- **MCP Server**: The central server that registers and routes tool execution requests
- **Tool Registry**: Manages the available tools, ensuring each tool is validated and can be executed
- **Context System**: Sophisticated state management with parent-child relationships for complex workflows
- **Agent Orchestration**: Intelligent routing between specialized agents based on query requirements
- **Guardrails System**: Configurable input and output validation to ensure safe and appropriate responses
### Agent Types
- **Research Agent**: Utilizes web search to gather and analyze information with citations
- **Database Agent**: Queries and analyzes data from Supabase databases
- **Customer Support Agent**: Handles user inquiries with natural language understanding
- **Specialized Agents**: Extensible framework for creating domain-specific agents
## 🔧 Configuration
Create a configuration file for the MCP server. Here's a sample configuration:
```json
{
"mcpServers": {
"openai-agent": {
"command": "node",
"args": [
"dist/index.js"
],
"env": {
"OPENAI_API_KEY": "YOUR_API_KEY_HERE",
"SUPABASE_URL": "https://your-supabase-project.supabase.co",
"SUPABASE_KEY": "YOUR_SUPABASE_KEY_HERE",
"LLM_DEBUG": "true",
"AGENT_LIFECYCLE": "true",
"TOOL_DEBUG": "true"
},
"disabled": false,
"autoApprove": [
"research",
"support",
"customer_support",
"database_query",
"handoff_to_agent",
"summarize"
]
}
}
}
```
## 🏃♂️ Usage
### As a Command Line Tool
```bash
# Set required environment variables
export OPENAI_API_KEY=your_api_key_here
export SUPABASE_PROJECT_ID=your_project_id
export SUPABASE_ACCESS_TOKEN=your_access_token
# Run the MCP server
agentic-mcp
```
### As a Library
```javascript
import { OpenAIAgentMCPServer } from '@agentics.org/agentic-mcp';
const server = new OpenAIAgentMCPServer({
name: 'openai-agent',
version: '1.0.0',
openai: {
apiKey: process.env.OPENAI_API_KEY,
defaultModel: 'gpt-4o-mini'
},
tracing: {
enabled: true,
level: 'debug'
},
tools: {
enabled: ['research', 'database_query', 'customer_support', 'handoff_to_agent', 'summarize'],
config: {
database: {
projectId: process.env.SUPABASE_PROJECT_ID,
key: process.env.SUPABASE_ACCESS_TOKEN
},
openai: {
apiKey: process.env.OPENAI_API_KEY
}
}
},
guardrails: {
enabled: true,
rules: []
}
});
server.serve().catch(error => {
console.error("❌ Server error:", error);
process.exit(1);
});
```
## 🧩 Advanced Features
### Context Management System
The Agentic MCP includes a sophisticated context management system that enables:
- **Hierarchical Context**: Parent-child relationships for complex agent workflows
- **State Tracking**: Persistent state across multiple interactions
- **Memory Management**: Store and retrieve information across agent calls
- **Resource Sharing**: Share resources between agents in a workflow
- **Action Tracking**: Monitor and log agent actions for auditing and debugging
```javascript
// Example of context management
const context = new Context();
context.initializeWorkflow();
context.remember('user_preference', { theme: 'dark' });
context.trackAction('research_initiated');
```
### Agent Orchestration
The system supports sophisticated agent orchestration patterns:
- **Dynamic Routing**: Automatically route queries to the most appropriate agent
- **Handoff Protocol**: Seamlessly transfer control between specialized agents
- **Workflow Tracking**: Maintain context and state across agent transitions
- **Multi-Agent Collaboration**: Enable multiple agents to work together on complex tasks
```javascript
// Example of agent handoff
const handoffTool = {
name: "handoff_to_agent",
description: "Transfer the conversation to another specialized agent",
parameters: {
type: "object",
properties: {
agent_name: {
type: "string",
enum: ["researcher", "database_expert", "customer_support"]
},
reason: {
type: "string"
}
},
required: ["agent_name", "reason"]
},
execute: async (params) => {
// Handoff logic
}
};
```
### Guardrails System
The Agentic MCP includes a configurable guardrails system for ensuring safe and appropriate responses:
- **Input Validation**: Filter and validate user inputs before processing
- **Output Validation**: Ensure agent responses meet safety and quality standards
- **Custom Rules**: Define custom validation rules for specific use cases
- **Failure Handling**: Graceful handling of guardrail violations
```javascript
// Example guardrail implementation
const customGuardrail = {
async check(msgs, context) {
// Validation logic
return true;
},
onFailure(msgs, context) {
// Failure handling
}
};
```
### Streaming Support
The system supports real-time streaming responses for interactive applications:
- **Partial Results**: Stream partial results as they become available
- **Tool Call Events**: Stream tool call events for visibility into agent actions
- **Progress Indicators**: Provide progress updates during long-running operations
```javascript
// Example of streaming usage
const streamIterator = AgentRunner.run_streamed(agent, [input]);
for await (const event of streamIterator) {
// Process streaming event
console.log(event.delta);
}
```
## 🛠️ Creating and Using Tools
### Creating a New Tool
1. **Create a New Module**: Add a new TypeScript file in the `src/mcp/tools/` directory
2. **Implement the Interface**: Your tool should implement the `MCPTool` interface
3. **Register the Tool**: Update the tool registration logic in `src/mcp/server.ts` to include the new tool
```typescript
// Example tool implementation
export class CustomTool implements MCPTool {
name = 'custom_tool';
description = 'Description of your custom tool';
inputSchema = {
type: 'object',
properties: {
param1: {
type: 'string',
description: 'Description of parameter 1'
}
},
required: ['param1']
};
async execute(params: any, context: Context): Promise<any> {
// Tool implementation
return { result: 'Success' };
}
}
```
### Using the Tools
- **Tool Requests**: MCP clients issue requests by specifying the tool name and parameters
- **Web Search Integration**: The research tool utilizes the `gpt-4o-search-preview` model with web search enabled
- **Approval**: Tools must be listed in the `autoApprove` section of the MCP settings
## 🔍 Troubleshooting and Debugging
- **Logging**: The server is configured with tracing options (LLM_DEBUG, AGENT_LIFECYCLE, TOOL_DEBUG)
- **Registry Debugging**: The `ToolRegistry` class logs tool registration and execution details
- **Web Search**: For the research tool, ensure that the model `gpt-4o-search-preview` is used
- **Context Inspection**: Examine the context state for debugging complex workflows
- **Action Tracking**: Review tracked actions to understand agent behavior
## 📄 License
MIT
## 👥 Contributors
- Agentics Foundation ([@agenticsorg](https://github.com/agenticsorg))
- rUv ([@ruvnet](https://github.com/ruvnet))
Created by the Agentics Foundation