MCP Demo Server

A demonstration MCP (Model Context Protocol) server showcasing Tools, Resources, and Prompts with integrated security scanning.

Features

🛠️ Tools (6)

add - Add two numbers
reverse_text - Reverse a string
format_json - Pretty-print JSON
calculate - Evaluate mathematical expressions
scan_mcp_server - Scan MCP servers for vulnerabilities
check_scanner_status - Check scanner configuration

📚 Resources (4)

demo://info - Server metadata
demo://timestamp - Current time and uptime
demo://examples - Usage examples
demo://file/data - Read sample data

💬 Prompts (3)

code_review - Code review template
summarize - Text summarization template
debug_helper - Debugging assistance template

Quick Start

Prerequisites

Python 3.11+
uv package manager

Installation

# Clone the repository
git clone https://github.com/manutri1986/mcpdeployment.git
cd mcpdeployment

# Install dependencies (automatic with uv)
uv sync

Run the Server

Local Development (stdio transport):

# Start MCP server for IDE integration
uv run mcp-server

The server communicates via stdio and will wait for MCP protocol connections.

Remote Deployment (HTTP transport):

# Start HTTP server for remote access
MCP_REMOTE_HOST=127.0.0.1 MCP_REMOTE_PORT=8000 uv run mcp-server-remote

# Or use the test script
./scripts/test_http_local.sh

📖 Full HTTP deployment guide: docs/HTTP_DEPLOYMENT.md

Security Scanning

Quick Scan

# Run security scan (YARA analyzer - fast, no API key needed)
uv run python scripts/scanners/yara_scanner.py

# Quick scan (sample components only)
uv run python scripts/scanners/yara_scanner.py --quick

# Advanced scanners (require API keys)
uv run python scripts/scanners/llm_api_scanner.py       # OpenAI LLM analysis
uv run python scripts/scanners/cisco_api_scanner.py     # Cisco AI Defense

Scanner Coverage:

✅ Tools (6) - All scanned
✅ Prompts (3) - All scanned
⚠️ Resources (4) - Cannot scan via stdio

Setup Advanced Scanning (Optional)

For deeper analysis with LLM and API analyzers:

# Run setup script
./scripts/setup_scanner.sh

# Or set environment variables manually
export MCP_SCANNER_API_KEY="your_api_key"
export MCP_SCANNER_ENDPOINT="https://us.api.inspect.aidefense.security.cisco.com/api/v1"

Get your API key: Cisco AI Defense

📖 Full documentation: docs/SCANNER_SETUP.md

Using with MCP Clients

Cursor IDE

Configuration included at .cursor/mcp.json. After setup:

Restart Cursor IDE
Test: "Use the add tool to calculate 5 + 3"
Or: "Access the demo://info resource"

Claude Desktop, VS Code, Windsurf

Add to your MCP client configuration:

{
  "mcpServers": {
    "mcpdeployment": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/manutri1986/mcpdeployment.git",
        "mcp-server"
      ]
    }
  }
}

Configuration file locations:

Client	Config Path
Claude Desktop (macOS)	`~/Library/Application Support/Claude/claude_desktop_config.json`
Claude Desktop (Windows)	`%APPDATA%\Claude\claude_desktop_config.json`
Cursor	`.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global)
Windsurf	`~/.codeium/windsurf/mcp_config.json`
VS Code	`.vscode/mcp.json` or User settings
Claude Code	`.claude/mcp.json` (project) or `~/.claude/mcp.json` (global)

Project Structure

mcpdeployment/
├── src/mcpserver/          # MCP server implementation
│   ├── __init__.py
│   ├── __main__.py         # Entry point (stdio transport)
│   ├── __main_remote__.py  # Entry point (HTTP transport)
│   └── server.py           # Tools, resources, prompts
├── scripts/                # Utility scripts
│   ├── scanners/          # Security scanner implementations
│   │   ├── yara_scanner.py
│   │   ├── llm_api_scanner.py
│   │   └── cisco_api_scanner.py
│   ├── setup_scanner.sh   # Scanner configuration
│   └── test_http_local.sh # Local HTTP testing
├── tests/                  # Test files
│   └── test_scanner.py    # Test scanner setup
├── reports/                # Generated scan reports (gitignored)
├── docs/                   # Documentation
│   ├── methodology/       # Scanner methodology docs
│   ├── SCANNER_SETUP.md
│   ├── SCANNER_LIMITATIONS.md
│   └── HTTP_DEPLOYMENT.md # Remote deployment guide
├── data/                   # Sample data
│   └── sample_data.json
├── STRUCTURE.md           # Detailed structure guide
├── CLAUDE.md              # AI assistant guidance
├── README.md              # This file
└── pyproject.toml         # Project configuration

📖 See STRUCTURE.md for detailed directory structure and purpose.

Architecture

Built with FastMCP, a Python framework for MCP servers.

Key Pattern:

from mcp.server.fastmcp import FastMCP
mcp = FastMCP("Demo")

@mcp.tool()
def your_tool(arg: type) -> type:
    """Tool description"""
    return result

@mcp.resource("uri://path")
def your_resource() -> str:
    """Resource description"""
    return json.dumps(data)

@mcp.prompt()
def your_prompt(arg: type) -> str:
    """Prompt description"""
    return f"Prompt text with {arg}"

See CLAUDE.md for detailed architecture notes.

Development

Test Scanner

# Verify scanner is configured
uv run python tests/test_scanner.py

Adding Components

Edit src/mcpserver/server.py:

Add function with appropriate decorator (@mcp.tool(), @mcp.resource(), @mcp.prompt())
Update scanner scripts in scripts/scanners/ to include new tools/prompts in scan lists
Run security scan: uv run python scripts/scanners/yara_scanner.py

Documentation

CLAUDE.md - Development guide for AI assistants
docs/HTTP_DEPLOYMENT.md - Remote HTTP deployment guide
docs/SCANNER_SETUP.md - Scanner configuration
docs/SCANNER_LIMITATIONS.md - What can/cannot be scanned

Troubleshooting

Server won't start

Check Python version: uv run python --version (needs 3.11+)
Reinstall dependencies: uv sync

Tools not appearing in client

Restart client completely
Check client logs for errors
Verify configuration file syntax

Scanner errors

Verify installation: uv pip list | grep cisco-ai-mcp-scanner
Test setup: uv run python tests/test_scanner.py

License

MIT

mcpdeployment