AI导哈

联系人管理服务器

MCP服务器用于查询和管理跨PostgreSQL和Oracle数据库的联系人、交易和活动。

  • by lv-alex
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 lv-alex/contact-mcp

使用说明

联系MCP服务器

MCP服务器，用于查询和管理PostgreSQL和Oracle数据库中的联系人、事务和活动。

特性

  • 多数据库支持：PostgreSQL和Oracle（通过数据库链接）
  • 联系人管理：查询联系人和联系方式
  • 交易查询：在主事务表和归档事务表中搜索
  • 活动创建：创建活动并重新排队交易
  • 护栏：内置安全限制和数据编辑

建筑

┌─────────────────────────────────────────────────────────────┐
│                      MCP Server                              │
├─────────────────────────────────────────────────────────────┤
│  Tools: select_records, select_transactions,                │
│         select_contact, create_campaign,                    │
│         create_campaign_from_query, ...                     │
├─────────────────────────────────────────────────────────────┤
│                    Database Layer                            │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐ │
│  │ PostgreSQL  │  │ Oracle      │  │ Oracle DB Links     │ │
│  │ (contacts)  │  │ (config)    │  │ (tx/dw databases)   │ │
│  └─────────────┘  └─────────────┘  └─────────────────────┘ │
└─────────────────────────────────────────────────────────────┘

数据模型：

  • client 桌子→ has client_id, dialing_db, reporting_db
  • skill 桌子→ links client_id 到 skill_id （一个客户→ 许多技能）
  • transaction 桌子→ CLIENT_ID 列实际上是 skill_id （传统命名）
  • campaign 桌子→ 两者都有 client_id 和 skill_id

设置

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

配置

创建一个 .env 包含以下变量的文件：

PostgreSQL（用于联系人）

PGHOST=your-host
PGPORT=5432
PGDATABASE=your-db
PGUSER=your-user
PGPASSWORD=your-password
PGSSLMODE=require

Oracle（用于配置、事务、活动）

ORACLE_HOST=your-oracle-host
ORACLE_PORT=1521
ORACLE_SERVICE=your-service
ORACLE_USER=your-user
ORACLE_PASSWORD=your-password

可选的

ORACLE_DSN=full-dsn-string           # Overrides host/service/port
ORACLE_CLIENT_TABLE=lvousr.client    # Default client table
TX_ARCHIVE_COUNT=2                   # Number of archive tables to scan (0-2)

跑

source .venv/bin/activate
set -a && source .env && set +a
contact-mcp

MCP客户端配置

VS代码(.vscode/mcp.json)

{
  "servers": {
    "contact": {
      "command": "bash",
      "args": ["-c", "cd /path/to/contact && source .venv/bin/activate && contact-mcp"],
      "envFile": "${workspaceFolder}/.env"
    }
  }
}

克劳德桌面

{
  "mcpServers": {
    "contact": {
      "command": "/bin/bash",
      "args": [
        "-lc",
        "cd /path/to/contact && source .venv/bin/activate && set -a && source .env && set +a && contact-mcp"
      ]
    }
  }
}

工具

查询工具

工具 说明
select_records(table, filters, columns, limit, offset, order_by) 查询允许的表（联系人、contact_details）
count_records(table, filters) 统计表中的记录
get_contact_with_details(lvaccount_id) 通过ID获取所有详细信息
select_contacts_with_details(...) 使用详细信息加入联系人
select_transactions(client_id, filters, columns, limit, order_by) 跨主表+归档表查询事务
select_contact(client_id, filters, columns, limit, order_by) 通过Oracle数据库链接查询联系人
select_campaigns(filters, columns, limit, order_by) 从配置数据库查询活动

活动工具

工具 说明
create_campaign(client_id, data) 创建新活动
create_campaign_from_query(client_id, query_filters, campaign_data) 创建活动并插入匹配的交易

筛选器语法

过滤器支持多种运算符：

# Simple equality
{"outcome": "FAILED"}

# Operators via list [operator, value]
{"date_modified": [">=", "2026-02-17"]}
{"total_amount": [">", 1000]}

# Operators via dict
{"outcome": {"op": "in", "value": ["FAILED", "NO_ANSWER"]}}

# Supported operators:
# =, !=, >, >=, <, <=, like, not_like, in, not_in, between, is_null, is_not_null

使用示例

查询联系人

"Get contact and details for lvaccount_id 123456."
"List 10 contacts created in the last 7 days."
"Find contacts with phone1_sms_consent = true and do_not_dial = false."

查询交易记录

"Show the last 25 transactions for client 150723."
"List failed SMS transactions for skill 150747 in the last 2 days."
"Find transactions with outcome = 'NO_ANSWER' for client 150723."

重要提示： 这 CLIENT_ID 交易中的列实际上是 skill_id.过滤时：

  • 提供 client_id 按skill_id筛选的过滤器
  • 刀具参数 client_id 是实际的客户端（用于数据库查找）

创建活动

"Create a campaign for client 150723 with filename 'test_campaign'."

"Retry failed SMS for skill 150747 from the last 2 days."
# This uses create_campaign_from_query with:
# query_filters: {"client_id": 150747, "lvtransaction_type": "SMS", "outcome": "FAILED", "date_modified": [">=", "2026-02-18"]}

护栏

服务器包括内置的安全限制：

查询限制

  • MAX_ROWS：10000（每次查询的最大行数）
  • DEFAULT_LIMIT: 100
  • MAX_OFFSET: 100,000
  • POSTGRES_TIMEOUT_MS: 30,000
  • ORACLE_TIMEOUT_SECONDS: 30
  • MAX_IN_VALUES：1000（in子句中的值）
  • MAX_FILTERS: 20

允许的操作

  • 选择: contact, contact_details, campaign
  • 插入: campaign, transaction （通过create_campaign_rom_query）
  • 已屏蔽：删除、更新、删除、截断、更改、创建、授予、撤销

数据消减

敏感列会自动编辑： ssn, dob, password, password_hash, api_key, secret, token

数据库类型检测

服务器根据数据库链接命名自动检测Oracle与PostgreSQL：

  • lv*stg4a* → 甲骨文
  • lv*stg4b* → PostgreSQL

发展

运行测试

pytest tests/

检查语法

python3 -m py_compile contact_mcp/*.py

备注

  • 跨主表+归档表查询事务（可通过以下方式配置 TX_ARCHIVE_COUNT)
  • 活动始终插入Oracle配置数据库中（不通过数据库链接）
  • 事务插入（用于重新排队）通过数据库链接转到拨号数据库

相关 MCP