ramaibrm/amanahfy-mcp-server

Amanahfy AI MCP Server

A production-ready Model Context Protocol (MCP) server that provides AI tools & resources with access to Amanahfy APIs & services. Built with TypeScript and following clean architecture principles.

🚀 Features

• Dual Transport Support: STDIO (Claude Desktop) and HTTP (testing/development)
• Clean Architecture: 5-layer architecture with separation of concerns
• CLI Tools: Command-line interface for direct API testing
• Resource Access: URI-based resource references (campaign://slug, ip://address)
• Type Safety: Full TypeScript implementation with Zod validation

📋 Prerequisites

• Node.js (>=18.0.0): Download
• Git: For version control
• Claude Desktop: For MCP integration (Optional)

⚡ Quick Start

1. Installation

# Clone the repository
git clone <your-repo-url>
cd amanahfy-ai-mcp

# Install dependencies
npm install

# Build the project
npm run build

2. Claude Desktop Integration

Add to your Claude Desktop configuration (claude_desktop_config.json):

{
    "mcpServers": {
        "amanahfy-ai-mcp": {
            "command": "node",
            "args": [
                "C:\\path\\to\\campaign-agent-mcp-server\\dist\\index.js"
            ],
            "env": {
                "TRANSPORT_MODE": "stdio"
            }
        }
    }
}

3. Test the Connection

Restart Claude Desktop completely, then ask Claude:

• "Look up the campaign gaza-100k-in-72hrs"
• "What's the location of IP 8.8.8.8?"

💻 CLI Usage

Test functionality directly from the command line:

Campaign Commands

# Get campaign details
npm run cli -- get-campaign-details gaza-100k-in-72hrs

# With custom options
npm run cli -- get-campaign-details gaza-100k-in-72hrs --timeout 5000 --retries 1

🏗️ Architecture

The server follows a clean 5-layer architecture:

├── CLI Layer (src/cli/)           # Command-line interfaces
├── Tools Layer (src/tools/)       # MCP tool definitions
├── Resources Layer (src/resources/) # MCP resource handlers
├── Controllers Layer (src/controllers/) # Business logic
├── Services Layer (src/services/) # External API integration
└── Utils Layer (src/utils/)       # Shared utilities

⚙️ Configuration

Environment Variables

Create a .env file in the project root:

# Transport Configuration
TRANSPORT_MODE=stdio
PORT=8000
DEBUG=false
NODE_ENV=production

# API Configuration
AMANAHFY_API_BASE=https://api.amanahfy.com/api

# Optional API Keys
# IPAPI_API_TOKEN=your_api_token_here

Available Scripts

# Development
npm run build          # Compile TypeScript
npm run dev:stdio      # Run in STDIO mode with debug
npm run dev:http       # Run in HTTP mode with debug

# MCP Server Modes
npm run mcp:stdio      # STDIO transport (for Claude Desktop)
npm run mcp:http       # HTTP transport (for testing)

# Testing & Development
npm run cli            # CLI mode
npm run test           # Run tests
npm run lint           # Run ESLint
npm run format         # Format with Prettier

# Debugging
npm run mcp:inspect    # Launch with MCP Inspector

🧪 Testing & Development

MCP Inspector (Recommended)

Test your MCP server with the official inspector:

# Launch server with inspector
npm run mcp:inspect

# Then open: http://localhost:3000/mcp

Manual Testing

# Test HTTP mode
npm run mcp:http

# Test specific endpoints
curl http://localhost:8000/mcp

CLI Testing

# Test campaign lookup
npm run cli -- get-campaign-details gaza-100k-in-72hrs

# Test IP lookup
npm run cli -- get-ip-details 8.8.8.8

🔧 Troubleshooting

Common Issues

1. "Not valid JSON" error

   • Ensure no console output is interfering with STDIO mode
   • Check that TRANSPORT_MODE=stdio in Claude Desktop config

2. Module not found errors

   • Run npm run build after any code changes
   • Verify all dependencies are installed: npm install

3. API timeout errors

   • Check network connectivity
   • Increase timeout values in tool parameters
   • Verify API endpoints are accessible

4. Claude Desktop connection issues

   • Use absolute paths in config
   • Restart Claude Desktop completely after config changes
   • Check Claude Desktop logs for detailed error messages

Debug Mode

Enable detailed logging:

DEBUG=true
NODE_ENV=development

Need help? Open an issue or check the troubleshooting section above.