# 🤖 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
```bash
npm install
```

### 2. Configure Real AI (Recommended)
```bash
npm run setup-ai               # Interactive AI setup wizard
```
**OR** manually create `.env` with your API keys (see [AI Setup Guide](AI-SETUP-GUIDE.md))

### 3. Start the Server
```bash
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
```javascript
// 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
```javascript
await client.callTool("smart_file_analysis", {
  path: "package.json",
  analysis_type: "all"  // summary, structure, quality, security, all
});
```

### Weather-Based Planning
```javascript
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)
```bash
# 🚀 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`:
```json
{
  "agentic-ai-server": {
    "command": "node",
    "args": ["agentic-server.js"],
    "description": "Agentic AI MCP Server with natural language processing"
  }
}
```

### Client Development
```javascript
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:
```bash
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
```bash
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`:

```bash
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
```bash
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!** 🚀