Under 5 Minutes

计费数据MCP服务器（Python）

一个易于使用的模型上下文协议（MCP）服务器，用于与CSV文件中存储的计费数据进行交互。此服务器提供三个主要操作： 找到, 插入，以及 获取详细信息 用于计费记录。

🎯 项目概述

创建此MCP服务器是为了演示如何使用Python在5分钟内构建一个简单但功能齐全的MCP服务器。它为管理以CSV格式存储的计费数据提供了一个实用的界面，使其易于：

• 按各种条件搜索和过滤账单记录
• 插入具有自动计算功能的新账单记录
• 检索特定发票的完整详细信息
• 通过适当的验证保持数据完整性
• 利用pandas实现高效的CSV操作

🚀 特性

1. 查找账单记录 (find_billing_records)

使用多个条件搜索和过滤账单记录：

• 客户ID
• 国家和货币
• 产品ID和服务类别
• 发票状态（已支付、待处理、已取消、有争议）
• 金额范围（最小/最大）
• 日期范围
• 结果限制

2. 获取发票详细信息 (get_invoice_details)

按ID检索特定发票的完整信息，包括：

• 客户信息
• 产品详情
• 财务计算
• 税务信息
• 发票状态

3. 插入账单记录 (insert_billing_record)

添加新的账单记录，包括：

• 自动生成发票ID
• 财务计算（净值、税额、总额）
• 数据验证
• 日期标志

📁 项目结构

MCP-server-under-5-minutes/
├── src/
│   ├── server.py          # Main MCP server implementation
│   ├── billing_utils.py   # CSV operations and business logic (pandas-based)
│   └── Test/
│       ├── manual_test.py     # Manual MCP protocol test
│       ├── simple_test.py     # Direct utility testing
│       ├── test_server.py     # Comprehensive server testing
│       └── usage_examples.py  # Business scenario examples
├── billing_data.csv       # Sample billing data (10,000+ records)
├── requirements.txt       # Python dependencies (mcp, pandas)
├── setup.sh              # Automated setup script
├── venv/                  # Python virtual environment
└── README.md             # This documentation

🛠️ 安装说明

先决条件

• Python 3.8+
• pip包管理器

快速设置（一个命令）

# Make setup script executable and run it
chmod +x setup.sh && ./setup.sh

手动安装步骤

1. 克隆或导航到项目目录：

   cd /path/to/MCP-server-under-5-minutes

1. 创建并激活Python虚拟环境：

   python3 -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

1. 安装Python依赖项：

   pip install -r requirements.txt

1. 验证CSV数据文件是否存在：

确保 billing_data.csv 与您的计费数据一起位于根目录中。

测试服务器

1. 测试核心功能（直接效用测试）：

   source venv/bin/activate
   python src/Test/simple_test.py

1. 测试MCP协议（完成服务器测试）：

   source venv/bin/activate  
   python src/Test/manual_test.py

1. 查看使用示例：

   source venv/bin/activate
   python src/Test/usage_examples.py

运行MCP服务器

启动服务器（用于MCP客户端连接）：

source venv/bin/activate
python src/server.py

服务器将运行并等待MCP客户端通过stdio连接。

📊 数据格式

CSV文件应包含以下列：

🔧 用法示例

查找记录

# Find all paid invoices
{
  "name": "find_billing_records",
  "arguments": {
    "invoice_status": "Paid",
    "limit": 10
  }
}

# Find invoices for a specific customer
{
  "name": "find_billing_records", 
  "arguments": {
    "customer_id": "CUST-2824-IND"
  }
}

# Find high-value invoices in USD
{
  "name": "find_billing_records",
  "arguments": {
    "currency": "USD",
    "min_amount": 10000,
    "limit": 5
  }
}

# Find invoices by date range and country
{
  "name": "find_billing_records",
  "arguments": {
    "country": "US",
    "date_from": "2024-01-01", 
    "date_to": "2024-12-31"
  }
}

获取发票详细信息

{
  "name": "get_invoice_details",
  "arguments": {
    "invoice_id": "INV-2024-000001"
  }
}

插入新记录

{
  "name": "insert_billing_record",
  "arguments": {
    "customer_id": "CUST-9999-NEW",
    "country": "US",
    "currency": "USD", 
    "product_id": "LAP-ULTRA",
    "service_category": "Laptop",
    "quantity": 2,
    "unit_price": 1599.99,
    "tax_rate": 0.08,
    "invoice_status": "Pending"
  }
}

🔍 工具说明

1. find_billing_records

目的： 根据各种条件搜索和过滤账单记录。

参数：

• customer_id （可选）：按客户ID筛选
• country （可选）：按国家代码筛选
• currency （可选）：按货币筛选
• product_id （可选）：按产品ID筛选
• service_category （可选）：按服务类别筛选
• invoice_status （可选）：按状态筛选
• min_amount （可选）：最低总金额
• max_amount （可选）：最大总金额
• date_from （可选）：开始日期（YYYY-MM-DD）
• date_to （可选）：结束日期（YYYY-MM-DD）
• limit （可选）：最大结果（默认值：50）

退货： 匹配的计费记录数组

2. get_invoice_details

目的： 检索特定发票的完整详细信息。

参数：

• invoice_id （必填）：要检索的发票ID

退货： 完整的发票记录或未找到错误

3. insert_billing_record

目的： 将新的账单记录添加到CSV文件中。

参数：

• customer_id （必填）：客户标识符
• country （必填）：国家代码
• currency （必填）：货币代码
• product_id （必填）：产品标识符
• service_category （必填）：产品类别
• quantity （必填）：项目数量
• unit_price （必填）：单位价格
• tax_rate （必填）：税率（0.0至1.0）
• invoice_status （必填）：状态（已支付/待定/已取消/有争议）

退货： 新创建的记录，具有自动生成的ID和计算

🚀 连接到克劳德桌面

步骤1：完成设置

首先，确保您的MCP服务器已设置并测试：

# Run the setup
./setup.sh

# Test the server works
source venv/bin/activate
python src/Test/manual_test.py

步骤2：查找Claude桌面配置位置

在macOS上：

~/Library/Application Support/Claude/claude_desktop_config.json

在Windows上：

%APPDATA%/Claude/claude_desktop_config.json

在Linux上：

~/.config/Claude/claude_desktop_config.json

步骤3：配置Claude桌面

创建或编辑 claude_desktop_config.json 文件：

{
  "mcpServers": {
    "billing-data": {
      "command": "python",
      "args": ["/Users/luciaharcekova/Documents/Projects/MCP-server-under-5-minutes/src/server.py"],
      "env": {
        "PYTHONPATH": "/Users/luciaharcekova/Documents/Projects/MCP-server-under-5-minutes",
        "PATH": "/Users/luciaharcekova/Documents/Projects/MCP-server-under-5-minutes/venv/bin:/usr/bin:/bin"
      },
      "cwd": "/Users/luciaharcekova/Documents/Projects/MCP-server-under-5-minutes"
    }
  }
}

⚠️ 重要提示： 替换 /Users/luciaharcekova/Documents/Projects/MCP-server-under-5-minutes 根据您的实际项目路径！

步骤4:重新启动克劳德桌面

1. 完全关闭克劳德桌面
2. 重新打开克劳德桌面
3. 寻找🔌 指示MCP工具可用的锤子图标

第五步：在克劳德进行测试

在Claude Desktop中尝试以下命令：

Can you find all paid invoices from the US with amounts over $10,000?

Show me the details for invoice INV-2024-000001

Add a new billing record for customer CUST-DEMO-001 from Canada, for a laptop worth $2000 CAD

⚡ 替代方案：手动MCP客户端测试

对于其他MCP客户端或手动测试：

# Start the server manually
source venv/bin/activate
python src/server.py

# The server communicates via stdio (JSON-RPC over stdin/stdout)

🧪 测试与验证

测试1：核心功能（直接测试）

source venv/bin/activate
python src/Test/simple_test.py

预期： ✅ 所有计费实用程序功能均正常工作

测试2:MCP协议（服务器测试）

source venv/bin/activate
python src/Test/manual_test.py

预期： ✅ 服务器响应MCP初始化和工具调用

测试3：查看业务示例

source venv/bin/activate
python src/Test/usage_examples.py

预期： 📊 显示业务场景的各种查询模式

测试4：实时服务器测试

# In Terminal 1 - Start the server
source venv/bin/activate
python src/server.py

# In Terminal 2 - The server should show this message:
# "Billing Data MCP Server running on stdio"

预期： 🚀 服务器启动并等待MCP客户端连接

🚀 发展

添加新功能

1. 新搜索条件： 添加到 find_records 方法in billing_utils.py
2. 新的验证规则： 修改 insert_record 方法
3. 新工具： 添加到中的工具列表 server.py 并实现处理程序

文件结构

• src/server.py -带有工具注册和处理程序的主MCP服务器
• src/billing_utils.py -使用pandas进行CSV操作的业务逻辑
• billing_data.csv -您的账单数据文件
• examples/ -使用示例和测试
• requirements.txt -Python依赖关系

📝 这是如何创建的

🔧 故障排除

服务器无法启动

# Check Python version (requires 3.8+)
python3 --version

# Reinstall dependencies
source venv/bin/activate
pip install --force-reinstall -r requirements.txt

# Check for import errors
python -c "from src.billing_utils import BillingUtils; print('✅ Imports work')"

克劳德桌面未检测到服务器

1. 检查配置文件位置 -确保编辑正确 claude_desktop_config.json
2. 验证路径 -在配置中使用绝对路径
3. 检查权限 -确保服务器文件可执行： chmod +x src/server.py
4. 重新启动克劳德 -完全关闭并重新打开Claude Desktop
5. 检查日志 -在Claude Desktop中查找MCP连接错误

数据问题

# Verify CSV file exists and has data
wc -l billing_data.csv
head -5 billing_data.csv

# Test data loading directly
python -c "import pandas as pd; print(f'✅ Loaded {len(pd.read_csv(\"billing_data.csv\"))} records')"