🤖 Agentic AI MCP Server

A sophisticated Model Context Protocol (MCP) server powered by real AI capabilities. This server provides natural language processing, multi-step planning, intelligent reasoning, and autonomous task execution with OpenAI and Anthropic integration.

✨ Features

🧠 Real AI Capabilities

• 🤖 OpenAI Integration: GPT-4o, GPT-4o-mini, GPT-3.5-turbo support
• 🧠 Anthropic Integration: Claude 3 (Haiku, Sonnet, Opus) support
• 🔄 Smart Fallback: Graceful degradation to mock AI if needed
• 💰 Cost-Optimized: Recommended models for best value
• 🔐 Secure: Environment-based API key management

🎯 Intelligent Features

• Natural Language Understanding: True comprehension with real AI
• Multi-Step Planning: Automatic task decomposition and execution
• Autonomous Reasoning: Context-aware decision making
• Memory & Context: Persistent conversation history
• Intelligent Synthesis: Coherent responses combining multiple tools

🔧 Smart Tools

• AI Assistant: Natural language interface powered by real AI
• Smart File Analysis: Deep code/text analysis with AI insights
• Weather Planner: Intelligent activity suggestions based on conditions
• Time Intelligence: Context-aware time and date responses
• File Operations: Enhanced with AI-powered insights

🚀 Quick Start

1. Installation

npm install

2. Configure Real AI (Recommended)

npm run setup-ai               # Interactive AI setup wizard

OR manually create .env with your API keys (see AI Setup Guide)

3. Start the Server

npm start                      # Start with real AI capabilities
npm run client              # Launch universal interactive client
npm run demo                # Try the demo mode

🎯 Architecture

This server features a clean, production-ready architecture optimized for AI capabilities:

src/
├── core/                   # 🧠 Shared AI Components
│   ├── memory.js          # Memory management system
│   ├── ai-agent.js        # AI reasoning and planning engine  
│   └── tools.js           # Shared tool definitions and execution
├── clients/               # � Smart Client Applications
│   └── universal.js       # Universal agentic AI client
└── index.js               # 🤖 Main agentic AI server

tests/                     # 🧪 Comprehensive Test Suite
├── agentic.test.js        # AI capabilities testing
└── integration.test.js    # End-to-end validation

examples/                  # 📚 Usage Examples & Demos
└── simple-client.js       # Basic client implementation

🔄 Architecture Benefits

• 📦 Modular Design: Shared core components eliminate code duplication
• 🧹 Clean Structure: Logical separation of servers, clients, tests, examples
• ⚡ Optimized Performance: Lazy loading, memory management, result caching
• 🔧 Better Maintainability: Single source of truth for AI logic and tools
• 🧪 Comprehensive Testing: Dedicated test suite with integration coverage
• 📚 Clear Examples: Focused examples for different use cases

📖 Usage Examples

Natural Language Interface

// Ask the AI assistant anything!
await client.callTool("ai_assistant", {
  request: "Analyze my TypeScript project and suggest architectural improvements",
  session_id: "my_session"
});

await client.callTool("ai_assistant", {
  request: "Help me organize these files using best practices",
  session_id: "my_session"
});

Smart File Analysis

await client.callTool("smart_file_analysis", {
  path: "package.json",
  analysis_type: "all"  // summary, structure, quality, security, all
});

Weather-Based Planning

await client.callTool("weather_planner", {
  city: "London",
  activity_type: "outdoor"  // outdoor, indoor, mixed
});

🧠 AI Intelligence Features

Multi-Step Planning

The AI automatically creates execution plans:

1. Request Analysis: Understands what you want to accomplish
2. Tool Selection: Chooses the best tools for each step
3. Execution: Runs tools in optimal sequence
4. Synthesis: Combines results into intelligent responses

Example Planning Process

User: "Analyze my project and suggest improvements"

AI Reasoning: "User wants project analysis. I should read files, analyze structure, and provide insights."

Execution Plan:
1. list_files (get project structure)
2. read_file (analyze key files like package.json)
3. ai_analyze_content (provide intelligent insights)

Result: Comprehensive analysis with specific recommendations

Memory & Context

• Session-based memory: Remembers your conversation
• Context awareness: Understands your project and preferences
• Learning: Improves responses based on your interactions

🔧 Available Tools

🤖 AI-Powered Tools

Tool	Description	Example Usage
ai_assistant	Natural language interface for complex tasks	"Help me refactor this code"
smart_file_analysis	AI-powered file analysis with insights	Analyze code quality, structure, security
weather_planner	Weather-based activity planning	Get activity suggestions for any city

📁 File Operations

Tool	Description
read_file	Read file contents with AI analysis
write_file	Write content to files
list_files	List directory contents with intelligent categorization
get_weather	Basic weather information

📚 AI Resources

Access advanced AI capabilities:

• ai://conversation-history - Your conversation memory
• ai://capabilities - Full AI feature documentation
• ai://reasoning-engine - How the AI makes decisions
• weather://cities - Available weather locations

🎯 Example Use Cases

Project Analysis

"Analyze my Node.js project structure and suggest improvements"
→ AI reads files, analyzes dependencies, suggests organization

Weather Planning

"Plan outdoor activities in Paris considering current weather"
→ AI checks weather, suggests appropriate activities with explanations

Code Review

"Review my TypeScript code for potential issues"
→ AI analyzes code quality, security, and best practices

File Organization

"Help me organize my project files using industry standards"
→ AI analyzes structure, suggests reorganization with reasoning

🛠️ Development

Available Commands (New Architecture)

# 🚀 Server Management
npm start                    # Start optimized agentic AI server
npm run start:traditional   # Start traditional TypeScript server
npm run dev                 # Development mode - traditional server
npm run dev:agentic         # Development mode - AI server

# 👥 Client Applications  
npm run client              # Universal auto-detecting client
npm run client:simple       # Basic example client
npm run demo                # Interactive demonstration

# 🧪 Testing & Validation
npm test                    # Test traditional server
npm run test:agentic        # Test AI capabilities  
npm run test:integration    # Test server switching
npm run test:all            # Run complete test suite

# 🔧 Development Tools
npm run build               # Build TypeScript components
npm run clean               # Remove redundant files (architectural cleanup)

Server Architecture

• agentic-server.js: Main AI-powered server
• src/index.ts: Traditional MCP server (TypeScript)
• Memory System: Conversation and context management
• AI Agent: Planning and reasoning engine
• Tool Orchestration: Intelligent multi-tool workflows

🤝 Integration

VS Code Extension

Configure in .vscode/mcp.json:

{
  "agentic-ai-server": {
    "command": "node",
    "args": ["agentic-server.js"],
    "description": "Agentic AI MCP Server with natural language processing"
  }
}

Client Development

const client = new Client({
  name: "my-agentic-client",
  version: "1.0.0"
});

// Connect to agentic server
const transport = new StdioClientTransport({
  command: "node",
  args: ["agentic-server.js"]
});

await client.connect(transport);

// Use natural language!
const result = await client.callTool("ai_assistant", {
  request: "What can you help me with?",
  session_id: "my_app"
});

📦 Dependencies

Core MCP

• @modelcontextprotocol/sdk - MCP protocol implementation
• zod - Schema validation

AI Capabilities

• openai - OpenAI API integration (optional)
• @anthropic-ai/sdk - Anthropic API integration (optional)
• uuid - Session management

Development

• typescript - Type safety for traditional server
• @types/node - Node.js type definitions

🔒 Configuration

AI Providers

Set environment variables for real AI:

export OPENAI_API_KEY="your-key-here"
export ANTHROPIC_API_KEY="your-key-here"

Or use the built-in mock AI for testing (no API keys required).

🧪 Testing

Comprehensive Testing

npm run test:agentic  # Test AI capabilities
npm run test         # Test traditional tools
npm run client       # Interactive testing

Example Test Sessions

1. Start server: npm run agentic
2. Open client: npm run client:interactive
3. Try: ai help me understand this project
4. Try: ai check weather in Tokyo and suggest activities

🌟 What Makes This Agentic?

Unlike traditional tool-based MCP servers, this agentic AI version:

• Understands Intent: Processes natural language to understand what you really want
• Plans Autonomously: Creates multi-step execution strategies without explicit instructions
• Reasons About Context: Makes intelligent decisions based on your situation
• Learns and Adapts: Improves responses based on conversation history
• Synthesizes Intelligence: Combines multiple data sources into coherent insights
• Proactive Assistance: Suggests improvements and alternatives you might not consider

📈 Legacy Tools (Backward Compatible)

The traditional MCP server is still available at src/index.ts:

npm run build  # Build TypeScript
npm start      # Run traditional server

Traditional Tools

• get_weather - Basic weather for cities
• read_file - Read file contents
• write_file - Write to files
• list_files - List directory contents

Legacy Client Examples

npm run client           # Simple test client
npm run client:advanced  # Advanced demo client
npm run client:typed     # TypeScript client

📈 Roadmap

• Real AI Integration: Connect OpenAI/Anthropic APIs for production use
• Advanced Memory: Persistent storage and long-term learning
• Plugin System: Extensible AI tool ecosystem
• Visual Interface: Web-based chat interface for AI interactions
• Multi-modal AI: Support for images, documents, and rich media

---

Transform your MCP experience from simple tool execution to intelligent AI assistance! 🚀