🚀 MCPCFC - ColdFusion MCP Server

MCPCFC — 全球首个 ColdFusion MCP 服务

现在，你的 ColdFusion 应用可以与 AI 对话了。AI 也可以使用你的 CF 工具。

MCPCFC 将 Adobe ColdFusion 连接到 Claude、ChatGPT、Cursor、VS Code 以及任何支持 Model Context Protocol 的其他 AI 助手。它可以将现有 CFML 代码转化为可供 AI 调用的工具，无需重写。

你有一个用于生成发票的 ColdFusion 函数？它现在就是一个 MCP 工具。一个用于查询专有数据库的函数？也是工具。一个用于启动内部工作流的函数？还是工具。只要 ColdFusion 能做到，AI 就能调用。

┌─────────────┐      ┌──────────────┐      ┌──────────────────┐
│   Claude /   │─────▶│    MCPCFC     │─────▶│  Your CF App     │
│   ChatGPT /  │◀─────│  MCP Server   │◀─────│  & Business Logic│
│   Cursor     │      └──────────────┘      └──────────────────┘
└─────────────┘       JSON-RPC 2.0          PDF, Email, DB,
                      + Stdio Bridge        Files, HTTP, ...

为什么这很重要

数百万行 ColdFusion 代码仍在生产环境中运行，服务于全球各地的政府机构、金融机构、医疗系统和企业。这些代码运行良好，但它们正日益与重塑人们工作方式的 AI 工具相隔离。

MCPCFC 填补了这一鸿沟。你无需用 Python 或 TypeScript 重写 CF 业务逻辑，只需将其封装为 MCP 工具，就能让 AI 助手直接调用。你的遗留代码库一夜之间就能成为连接 AI 的资产。

适用对象：

• 企业团队：拥有多年 CF 业务逻辑，希望在无需重写的情况下获得 AI 能力
• 政府机构：逐步实现遗留 CF 系统的现代化
• CF 开发者：希望基于现有可用功能构建新一代智能应用
• 数字化转型负责人：希望以低风险方式从遗留系统迈向前沿技术

包含内容

MCPCFC 附带六个概念验证工具，用于演示这一模式：

工具	功能
hello	简单问候，可用于验证连接
fileOperations	沙盒文件 I/O（read、write、list、delete、exists、info）
httpRequest	发起出站 HTTP 请求（会阻止访问私有／内部 IP）
pdf	使用 ColdFusion 内置 PDF 引擎生成 PDF、提取 PDF 文本并合并 PDF
queryDatabase	经过验证的只读 SQL 查询（仅限 SELECT）
sendEmail	通过 SendGrid 发送电子邮件（需要 SENDGRID_API_KEY）

这些工具有意保持简单。真正的强大之处在于添加自己的工具，详见下文的添加自定义工具。

测试环境

• ✅ macOS + Adobe ColdFusion 2025
• ⚠️ 尚未在 Windows/Linux 或其他 CFML 引擎（Lucee、BoxLang 等）上测试

快速开始

选项 1：浏览器测试客户端

1. 将此仓库克隆到 ColdFusion Web 根目录中（或创建符号链接）。
2. 访问：http://localhost:8500/mcpcfc/client-examples/test-client.cfm
3. 点击 Connect → List Tools → Call Hello Tool。

选项 2：Claude Desktop（本地 stdio）

Claude Desktop 通过 stdio 与本地 MCP 服务通信。MCPCFC 基于 HTTP，因此附带一个桥接脚本，用于在两者之间进行转换。

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）：

{
  "mcpServers": {
    "coldfusion-mcp": {
      "command": "/absolute/path/to/mcpcfc/bridge/cf-mcp-bridge.sh",
      "env": {
        "MCPCFC_URL": "http://localhost:8500/mcpcfc"
      }
    }
  }
}

然后完全退出并重新启动 Claude Desktop。

选项 3：远程／Streamable HTTP

MCPCFC 还支持任何 MCP 客户端通过 HTTP 直接连接，地址为：

BASE_URL/endpoints/mcp.cfm

Claude Code、ChatGPT、Codex、Cursor、VS Code、Zed、Kimi 和 Antigravity 的可复制粘贴配置，请参见 CLIENTS.md。

添加自定义工具

从这里开始，MCPCFC 就能为你所用。每个工具都是一个继承自 AbstractTool 的 ColdFusion 组件（.cfc）。基类提供输入验证、结构化结果辅助方法，以及自动向 MCP 协议注册的功能。业务逻辑由你编写，繁杂的接入工作由 MCPCFC 处理。

模式

每个工具分为三个步骤：

1. 创建一个 .cfc 文件，放在 core/tools/ 中，并继承 AbstractTool
2. 在 init() 中定义工具——名称、描述和输入架构
3. 注册工具，在 MCPServer.cfc 中添加一行

就是这么简单。下面通过一个完整示例来说明。

示例：构建 WeatherTool

假设你想让 AI 助手能够通过外部 API 查询天气。以下是完整的工具：

步骤 1 — 创建 core/tools/WeatherTool.cfc：

/**
 * WeatherTool.cfc
 * Returns current weather for a given city
 */
component extends="AbstractTool" output="false" {

    public function init() {
        // 1. Identity — how the tool appears in MCP
        setName("getWeather");
        setTitle("Get Weather");
        setDescription("Returns current weather conditions for a given city name.");

        // 2. Input schema — tells the AI what parameters to send
        var inputSchema = structNew("ordered");
        inputSchema["type"] = "object";
        inputSchema["properties"] = structNew("ordered");

        var citySchema = structNew("ordered");
        citySchema["type"] = "string";
        citySchema["description"] = "City name (e.g., 'Pittsburgh', 'New York')";
        inputSchema.properties["city"] = citySchema;

        inputSchema["required"] = ["city"];
        setInputSchema(inputSchema);

        return this;
    }

    public struct function execute(required struct toolArgs) {
        // Validate the required parameter exists
        validateRequired(arguments.toolArgs, ["city"]);

        var city = trim(arguments.toolArgs.city);
        logExecution("Weather requested", { city: city });

        try {
            // Call an external weather API
            var apiUrl = "https://wttr.in/#encodeForURL(city)#?format=j1";

            var httpService = new http(method="GET", url=apiUrl, timeout=10);
            var response = httpService.send().getPrefix();

            if (response.statusCode contains "200") {
                var data = deserializeJson(response.fileContent);
                var current = data.current_condition[1];

                var result = {
                    "city": city,
                    "temperature_f": current.temp_F,
                    "temperature_c": current.temp_C,
                    "condition": current.weatherDesc[1].value,
                    "humidity": current.humidity & "%",
                    "wind_mph": current.windspeedMiles
                };

                // Return structured JSON — the AI will interpret it
                return jsonResult(result);
            } else {
                return errorResult("Weather API returned status: #response.statusCode#");
            }
        } catch (any e) {
            return errorResult("Failed to fetch weather: #e.message#");
        }
    }
}

步骤 2 — 在 core/MCPServer.cfc 中注册：

打开 core/MCPServer.cfc，并在 registerDefaultTools() 方法的 toolClasses 数组中添加你的工具类：

var toolClasses = [
    "core.tools.HelloTool",
    "core.tools.PDFTool",
    "core.tools.SendGridEmailTool",
    "core.tools.DatabaseTool",
    "core.tools.FileTool",
    "core.tools.HttpClientTool",
    "core.tools.WeatherTool"          // <-- add your tool here
];

步骤 3 — 重启并测试：

重启 ColdFusion 应用（访问 restart-app.cfm 或重启 CF 服务），然后重新启动 MCP 客户端。你的新工具会出现在工具列表中，AI 可以立即调用它。

基类提供的功能

AbstractTool.cfc 提供了一些辅助方法，让你可以专注于业务逻辑：

方法	用途
textResult(string)	返回纯文本响应
jsonResult(data)	返回结构化 JSON 数据
errorResult(message)	返回带有 isError 标志的错误
imageResult(base64Data, mimeType)	返回 base64 编码的图像
resourceResult(uri, text, mimeType)	返回嵌入式 MCP 资源
validateRequired(args, paramArray)	如果缺少必需参数，则抛出异常
validateTypes(args, typeMap)	验证参数类型（string、numeric、boolean、array、struct）
getParam(args, name, default)	获取参数，并在参数缺省时使用默认值
logExecution(message, data)	记录工具活动（如果已配置日志记录器）

实际应用中的工具创意

了解这一模式后，可以想想 ColdFusion 在你的组织中已经擅长处理哪些工作：

• 发票生成器 — 封装现有的 cfpdf 报表逻辑
• 客户查询 — 查询 CRM 数据库并向 AI 返回结果
• 文档转换器 — 利用 CF 内置的 Word/Excel/PDF 功能
• 邮件撰写工具 — 通过现有邮件基础设施撰写并发送邮件
• 报表运行器 — 执行存储过程并返回格式化结果
• 文件处理器 — 解析上传的 CSV、转换数据并写入输出文件
• 旧版 API 封装器 — 向 AI 暴露 SOAP 服务或内部 REST 端点

每个工具只需一个 .cfc 文件和一行注册代码。

冒烟测试

Stdio（推荐用于 Claude Desktop）

MCPCFC_URL="http://localhost:8500/mcpcfc" ./scripts/verify-stdio.sh

Streamable HTTP（用于远程客户端）

MCPCFC_URL="http://localhost:8500/mcpcfc" ./scripts/verify-http.sh

配置

编辑 config/settings.cfm 以自定义：

• protocolVersion（默认值：2025-06-18）
• defaultDatasource（默认值：mcpcfc_ds）
• 文件沙箱路径和大小限制
• CORS 设置

数据库设置（可选）

queryDatabase 工具需要一个名为 mcpcfc_ds 的 ColdFusion 数据源：

1. 在 ColdFusion Administrator 中配置数据源
2. 在浏览器中访问 database-setup.cfm 加载示例架构，或将 mcpcfc_db.sql 导入 MySQL/MariaDB

调试

• Claude Desktop MCP 日志（macOS）： ~/Library/Logs/Claude/mcp-server-coldfusion-mcp.log
• Bridge 调试模式： 在配置的 env 块中设置 MCPCFC_DEBUG=1
• 自签名 HTTPS： 如果使用不受信任的本地证书，请设置 MCPCFC_INSECURE=1

安全警告

MCPCFC 是一个功能强大的远程控制接口——它可以访问文件系统、发起 HTTP 请求、查询数据库、发送邮件和生成文档。请勿在未采取以下措施的情况下将其公开：

• 身份验证
• 严格的 CORS/来源限制
• 速率限制
• 针对每个工具的授权和沙箱隔离

项目结构

Application.cfc
bridge/
  cf-mcp-bridge.sh           # Stdio ⇄ HTTP bridge for Claude Desktop
client-examples/
  test-client.cfm             # Browser-based test interface
config/
  routes.cfm
  settings.cfm                # Server configuration
core/
  CapabilityManager.cfc
  JSONRPCHandler.cfc
  MCPServer.cfc                # Tool registration happens here
  TransportManager.cfc
  tools/
    AbstractTool.cfc           # Base class — extend this for custom tools
    DatabaseTool.cfc
    FileTool.cfc
    HelloTool.cfc              # Good reference for new tools
    HttpClientTool.cfc
    PDFTool.cfc
    SendGridEmailTool.cfc
endpoints/
  mcp.cfm                     # Unified MCP endpoint (JSON-RPC 2.0)
logging/
registry/
session/
scripts/
  verify-stdio.sh
  verify-http.sh

贡献

请参阅 CONTRIBUTING.md 了解相关指南。

许可证

MIT。请参阅 LICENSE。

---

使用 ColdFusion 2025 构建，作者为 @revsmoke。欢迎贡献。