kevinl2121/MCPServer

MCPServer

Agentic Mcp Server Demo.... VIRA! This is the preliminary MCP server for VIRA. VIRA Project to be released.

🤖 VIRA - Virtual Intelligent Recursive Agent

🔗 VIRA MCP Server

A clean, focused Model Context Protocol server that provides AI agent capabilities through standardized MCP tools.

This MCP server acts as a bridge between MCP clients (like Claude Desktop, Claude Code, Cursor) and VIRA's intelligent agent system, exposing agent capabilities through standard MCP tools.

🎯 What This Server Provides

Standard MCP Protocol Implementation

• Clean tool definitions and execution
• Proper error handling and responses
• Type-safe parameter validation
• Standardized MCP communication

Agent Integration Layer

• Coordinates with specialized AI agents
• Routes requests to appropriate agent capabilities
• Manages inter-agent communication
• Provides unified responses to MCP clients

🛠️ Available MCP Tools

Core Agent Tools

chat_with_agent

{
  "message": "Your message to the agent system",
  "mood": "excited" // optional: normal, excited, focused, creative
}

Intelligent conversation with context awareness and multi-agent coordination

task_execute

{
  "task": "Create a Python web scraper for news articles",
  "priority": "high", // low, medium, high, urgent
  "context": "Focus on RSS feeds and save to JSON format"
}

Autonomous task planning, decomposition, and execution

memory_manage

{
  "action": "add_goal", // get, set, add_goal, complete_goal, clear, export, analyze
  "key": "project_goals",
  "value": "Build a portfolio of 5 automation scripts"
}

Persistent memory, goal tracking, and context management

research_autonomous

{
  "topic": "Best practices for Python web scraping in 2024",
  "depth": "comprehensive", // quick, standard, comprehensive
  "output_format": "actionable_insights" // summary, report, analysis, actionable_insights
}

Intelligent research, analysis, and report generation

code_execute

{
  "language": "python", // python, javascript, bash, sql
  "code": "print('Hello from VIRA!')\nfor i in range(3): print(f'Count: {i}')",
  "timeout": 10,
  "save_output": true
}

Multi-language code execution with safety measures

Claude Code Integration Tools

claude_code_execute

{
  "command": "edit", // edit, view, create, analyze
  "prompt": "Add error handling to the main function",
  "files": ["/path/to/file.py"],
  "working_directory": "/project/path",
  "timeout": 60,
  "auto_approve": false
}

Direct Claude Code CLI integration for repository operations

claude_code_project_analysis

{
  "project_path": "/path/to/project",
  "analysis_type": "architecture", // overview, architecture, issues, improvements, documentation
  "include_files": ["*.py", "*.js"],
  "exclude_patterns": ["node_modules", ".git"]
}

Comprehensive project analysis and code review

claude_code_mcp_setup

{
  "action": "add", // add, remove, list, configure
  "server_name": "my-server",
  "server_command": "python3",
  "server_args": ["/path/to/server.py"],
  "environment": {"API_KEY": "value"},
  "scope": "user" // user, project
}

Manage other MCP servers within Claude Code

claude_code_repository_management

{
  "operation": "commit", // commit, branch, merge, review, refactor, test
  "target": "src/main.py",
  "message": "Add new feature implementation",
  "options": {"auto_stage": true}
}

Git workflow automation and repository management

Utility Tools

filesystem_virtual

{
  "action": "ls", // ls, cat, write, mkdir, cd, tree, find, rm, cp
  "path": "/projects/my-app",
  "content": "file contents", // for write operations
  "destination": "/backup/" // for copy operations
}

Virtual filesystem operations for file management

📋 Installation & Setup

1. Basic Installation

# Clone repository
git clone <repository-url>
cd vira-mcp-server

# Install dependencies
pip install -r requirements.txt

# Make executable
chmod +x main.py

2. MCP Client Configuration

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "vira-agent": {
      "command": "python3",
      "args": ["/absolute/path/to/vira-mcp-server/main.py"],
      "env": {
        "PYTHONPATH": "/absolute/path/to/vira-mcp-server"
      }
    }
  }
}

Claude Code (Project-scoped):

# Use the included .mcp.json file
cd vira-mcp-server
claude mcp list

Claude Code (User-scoped):

claude mcp add vira-agent -s user -- python3 /absolute/path/to/main.py

Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "vira-agent": {
      "command": "python3",
      "args": ["/absolute/path/to/vira-mcp-server/main.py"]
    }
  }
}

3. Verification

# Test server directly
python3 main.py

# Expected output:
# 🤖 VIRA Agent MCP Server v2.0 starting...
# 🎯 Planning Agent: Ready
# 🧠 Memory Agent: Ready
# 🔍 Research Agent: Ready
# 💻 Code Agent: Ready
# ⚡ Claude Code Integration: Available
# ✅ All systems ready - Server running!

🔧 Server Architecture

MCP Server (server.py)
├── Tool Routing Layer
│   ├── chat_* → ChatTool → All Agents
│   ├── task_* → TaskTool → PlanningAgent + Orchestrator
│   ├── memory_* → MemoryTool → MemoryAgent
│   ├── research_* → ResearchTool → ResearchAgent
│   ├── code_* → CodeTool → CodeAgent
│   ├── claude_code_* → ClaudeCodeTool → Claude CLI
│   └── filesystem_* → FilesystemTool → Virtual FS
├── Agent Orchestrator
│   ├── Message Routing
│   ├── Agent Coordination
│   └── System Monitoring
└── Specialized Agents
    ├── PlanningAgent (Task decomposition)
    ├── MemoryAgent (Context management)
    ├── ResearchAgent (Analysis & research)
    └── CodeAgent (Code execution)

📊 MCP Protocol Compliance

Supported Capabilities:

• ✅ Tools (function calling)
• ✅ Resources (file-like data access)
• ✅ Prompts (templated interactions)
• ✅ Proper error handling
• ✅ Type-safe parameter validation
• ✅ Async operation support

Transport Methods:

• ✅ STDIO (primary)
• ✅ HTTP (planned)
• ✅ SSE (planned)

Security Features:

• ✅ Input validation and sanitization
• ✅ Path traversal protection
• ✅ Command injection prevention
• ✅ Timeout enforcement
• ✅ Resource usage limits

🚀 Usage Examples

Basic Agent Interaction

# Through MCP client
{
  "tool": "chat_with_agent",
  "arguments": {
    "message": "Help me plan a web scraping project",
    "mood": "focused"
  }
}

# Response includes intelligent planning and next steps

Autonomous Task Execution

{
  "tool": "task_execute",
  "arguments": {
    "task": "Create a FastAPI application with authentication",
    "priority": "high",
    "context": "Include JWT tokens and user management"
  }
}

# Returns detailed execution plan and progress tracking

Code Analysis with Claude Code

{
  "tool": "claude_code_project_analysis",
  "arguments": {
    "project_path": "/my/project",
    "analysis_type": "issues",
    "include_files": ["*.py"]
  }
}

# Comprehensive code review with specific recommendations

🔍 Monitoring & Debugging

Health Check

# Check server status
curl -X POST http://localhost:3000/health
# or through MCP client tool calls

Debug Mode

# Enable debug logging
export VIRA_LOG_LEVEL=DEBUG
python3 main.py

Performance Metrics

The server tracks:

• Tool call frequency and latency
• Agent response times
• Error rates and types
• Resource usage
• Client connection status

⚙️ Configuration

Environment Variables

VIRA_LOG_LEVEL=INFO          # DEBUG, INFO, WARNING, ERROR
VIRA_AGENT_MODE=collaborative # collaborative, autonomous, debug
PYTHONPATH=.                 # Ensure proper module imports

Server Configuration

The server automatically configures:

• Tool registration and routing
• Agent initialization and orchestration
• Error handling and recovery
• Resource management and cleanup

🛡️ Security

Input Validation

• All tool parameters are validated against JSON schemas
• Path parameters checked for traversal attacks
• Command parameters sanitized for injection prevention

Execution Safety

• Code execution in sandboxed environments
• Timeout enforcement for all operations
• Resource usage monitoring and limits
• Permission-based operation controls

Data Protection

• No sensitive data logged
• Memory cleanup after operations
• Secure inter-agent communication
• Optional encryption for data at rest

🔧 Extending the Server

Adding New Tools

# 1. Create tool class
class MyTool:
    def get_tools(self) -> List[types.Tool]:
        return [types.Tool(name="my_tool", ...)]
    
    async def handle_tool_call(self, name: str, args: dict):
        # Implementation
        return [types.TextContent(type="text", text="Result")]

# 2. Register in server.py
self.tools["my_tool"] = MyTool()

Adding New Agents

# 1. Extend BaseAgent
class MyAgent(BaseAgent):
    def __init__(self):
        super().__init__("MyAgent", ["my_capability"])
    
    async def process_task(self, task: str, context: dict):
        # Implementation
        return {"success": True, "result": "..."}

# 2. Register with orchestrator
self.orchestrator.register_agent(MyAgent())

📈 Performance

Typical Response Times:

• Simple tool calls: < 100ms
• Agent coordination: < 500ms
• Code execution: < 5s
• Research tasks: < 30s
• Claude Code operations: < 10s

Throughput:

• Concurrent tool calls: 10+
• Agent message processing: 100+ msg/s
• File operations: 1000+ ops/s

🐛 Troubleshooting

Common Issues

"Tool not found"

• Verify tool registration in server.py
• Check tool name prefix routing
• Ensure proper tool class implementation

"Agent not responding"

• Check agent initialization in server startup
• Verify agent registration with orchestrator
• Review agent-specific error logs

"Claude Code integration failing"

• Verify Claude Code installation: claude --version
• Check PATH and permissions
• Review Claude Code MCP configuration

Debugging Steps

1. Enable debug logging: VIRA_LOG_LEVEL=DEBUG
2. Test individual components: Import and test agents directly
3. Check MCP client logs: Review client-side error messages
4. Verify tool schemas: Ensure parameter validation passes
5. Monitor resource usage: Check memory and CPU utilization

📚 Related Documentation

• MCP Protocol Documentation

The VIRA MCP Server provides a clean, standards-compliant interface to powerful AI agent capabilities. It handles all MCP protocol details so agents can focus on intelligence, while clients get reliable, type-safe access to autonomous AI capabilities. 🤖✨