🤖 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

📁 File Operations

📚 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! 🚀