Incident Agent

A Python FastMCP (Model Context Protocol) server for incident management and analysis.

This project provides a complete MCP server implementation with tools for greeting, echo functionality, and server information retrieval. It demonstrates the FastMCP framework capabilities and serves as a foundation for building more complex incident management tools.

Prerequisites

Python 3.13+
uv package manager

Setup

Clone the repository

git clone https://github.com/JayLiuMLP/incident-agent.git
cd incident-agent

Install dependencies
```
uv sync
```

Verify installation

uv run python -c "import fastmcp; print('FastMCP installed successfully!')"

MCP Server Usage

Available Tools

The server provides the following MCP tools:

hello - Greet a person or the world
echo - Echo back a message
server_info - Get server information and status

Available Resources

config://server/info - Server configuration information

Starting the MCP Server

Standard MCP Server (stdio transport)
```
uv run fastmcp run main.py
```

HTTP Server (for API access)

uv run fastmcp run main.py --transport http --port 8000

Inspect Server Configuration
```
uv run fastmcp inspect main.py
```

Testing the MCP Server

Method 1: Python Client (Recommended)

Use the built-in Python client utilities for easy testing:

# Run complete test suite (recommended)
uv run python mcp_client_utils.py

# Run comprehensive HTTP client test
uv run python http_client_test.py

Method 2: Using in Your Python Code

import asyncio
from mcp_client_utils import MCPClient, say_hello, echo_message

# Using utility functions
async def example():
    greeting = await say_hello("Developer")
    echo_result = await echo_message("Test message")
    print(f"Greeting: {greeting}")
    print(f"Echo: {echo_result}")

# Using client class
async def advanced_example():
    client = MCPClient("http://localhost:8000/mcp")
    tools = await client.list_tools()
    server_info = await client.get_server_info()
    print(f"Available tools: {tools}")
    print(f"Server version: {server_info['version']}")

# Run the examples
asyncio.run(example())
asyncio.run(advanced_example())

Method 3: Integration with MCP Clients

The server can be integrated with MCP-compatible clients like Claude Desktop by adding to your configuration:

{
  "mcpServers": {
    "incident-agent": {
      "command": "uv",
      "args": ["run", "fastmcp", "run", "main.py"],
      "cwd": "/path/to/incident-agent"
    }
  }
}

Method 4: HTTP API (curl)

⚠️ Note: HTTP API requires proper session management and is more complex. Python client is recommended.

For advanced users, you can use curl with the HTTP server:

# Start HTTP server first
uv run fastmcp run main.py --transport http --port 8000

# Test with Python client (much easier)
uv run python mcp_client_utils.py

Server Output Example

When running the test client, you should see:

🚀 MCP Client Tools Demo
Hello: Hello, Developer! 🌍 Welcome to the Incident Agent MCP Server!
Echo: Echo: This is a test message
Server status: running
Server version: 0.1.0
Available tools: ['hello', 'echo', 'server_info']

Development

Run the application
```
uv run python main.py
```
Run tests
```
uv run pytest
```
Setup pre-commit hooks
```
uv run pre-commit install
```

Test MCP functionality

# Quick test
uv run python mcp_client_utils.py

Quick Start

Want to test the MCP server right away? Follow these steps:

Install and setup (if not done already)

git clone https://github.com/JayLiuMLP/incident-agent.git
cd incident-agent
uv sync

Start the HTTP server (in one terminal)

uv run fastmcp run main.py --transport http --port 8000

Test with Python client (in another terminal)
```
uv run python mcp_client_utils.py
```

Expected output

🚀 MCP Client Tools Demo
Hello: Hello, Developer! 🌍 Welcome to the Incident Agent MCP Server!
Echo: Echo: This is a test message
Server status: running
Server version: 0.1.0
Available tools: ['hello', 'echo', 'server_info']

That's it! Your MCP server is working. 🎉

Project Structure

incident-agent/
├── main.py                     # Main MCP server entry point
├── run_server.py              # Server demo script
├── mcp_client_utils.py        # Primary Python client for testing (RECOMMENDED)
├── simple_client.py           # Simple Python client example
├── http_client_test.py        # Comprehensive HTTP client test
├── PYTHON_CLIENT_GUIDE.md     # Detailed Python client usage guide
├── HELLO_WORLD_MCP.md         # MCP server documentation
├── pyproject.toml             # Project configuration and dependencies
├── .cursorrules               # Development guidelines and best practices
└── src/incident_agent/        # Main application source
    ├── __init__.py           # Package initialization
    ├── server/               # MCP server implementation
    │   ├── __init__.py
    │   └── server.py         # FastMCP server definition
    └── tools/                # MCP tools implementation
        ├── __init__.py
        └── hello_tools.py    # Hello world tools

Key Files

main.py - MCP server entry point, use with fastmcp run
mcp_client_utils.py - RECOMMENDED Python client with utility functions and classes for testing
simple_client.py - Minimal client example for reference
src/incident_agent/server/server.py - Core server implementation
src/incident_agent/tools/hello_tools.py - Tool implementations

Troubleshooting

Common Issues

"Failed to connect to localhost" error
- Make sure the server is running: uv run fastmcp run main.py --transport http --port 8000
- Check if port 8000 is available: lsof -i :8000
curl requests don't work
- Use Python client instead (recommended): uv run python mcp_client_utils.py
- HTTP API with curl requires complex session management
"No such file or directory" error
- Make sure you're in the project directory
- Run uv sync to install dependencies
Import errors
- Ensure virtual environment is activated by using uv run prefix
- Check that FastMCP is installed: uv run python -c "import fastmcp; print('OK')"

Getting Help

Check PYTHON_CLIENT_GUIDE.md for detailed client usage
Check HELLO_WORLD_MCP.md for server implementation details
See .cursorrules for development guidelines

Contributing

This project follows FastMCP development best practices. See .cursorrules for detailed development guidelines.

MCP Servers