Halans MCP Server

Halans内容MCP服务器

此MCP（模型上下文协议）服务器为halans.com提供内容查询工具。它提供两种部署选项：用于直接集成Claude Desktop的基于本地stdio的服务器，以及用于远程访问的Cloudflare Workers部署。

可用工具

MCP服务器提供四种内容查询工具：

1. 搜索内容 -使用上下文搜索halans.com内容中的特定术语
2. get_section -按标题/标题检索特定章节
3. get_full_content -使用可选截断获取完整内容
4. get_content_summary -生成内容统计和目录

可用资源

MCP服务器还公开了三种可浏览的资源：

1. halans://content -来自halans.com的纯文本格式的完整内容
2. halans://content-summary -内容统计和分级目录
3. halans://articles-list -所有博客文章的结构化JSON列表，包括标题、日期、网址和摘录

快速开始

选项1：本地标准服务器（推荐）

1. 克隆和安装依赖关系：

git clone https://github.com/halans/halans-mcp-server
cd halans-mcp-server
npm install

1. 通过在MCP配置中添加以下内容来配置Claude Desktop：

{
  "mcpServers": {
    "halans-content": {
      "command": "node",
      "args": ["/path/to/halans-mcp-server/mcp-stdio.js"],
      "env": {}
    }
  }
}

1. 重新启动Claude Desktop，工具将可用。

选项2:Cloudflare Workers部署

1. 先决条件:

- 注册一个 Cloudflare帐户 - 安装 牧马人CLI

1. 通过Cloudflare进行身份验证:

npx wrangler login

1. 部署到Cloudflare Workers:

npm run deploy

这将把您的MCP服务器部署到以下URL： halans-mcp-server..workers.dev/sse

1. 一键部署 （备选方案）：


Cloudflare Workers功能

此MCP服务器利用了Cloudflare Workers的几个功能：

• 边缘计算：在全球用户附近运行，延迟低
• 耐用物品：维护有状态的MCP代理实例
• 服务器发送的事件：与MCP客户端实时通信
• 无冷启动：Cloudflare V8隔离的快速响应时间
• 内置可观察性：通过Cloudflare仪表板进行监控和分析

Worker配置

服务器公开了两个端点：

• /sse -MCP通信的服务器发送事件端点
• /mcp -标准MCP端点

配置在中管理 wrangler.jsonc:

{
  "name": "halans-mcp-server",
  "main": "src/index.ts",
  "compatibility_date": "2025-03-10",
  "durable_objects": {
    "bindings": [
      {
        "class_name": "MyMCP",
        "name": "MCP_OBJECT"
      }
    ]
  }
}

发展

与牧马人一起进行本地开发

# Start the Cloudflare Workers dev server
npm run dev

# Run TypeScript type checking
npm run type-check

# Format code
npm run format

# Fix linting issues
npm run lint:fix

使用Stdio服务器进行本地开发

# Test the stdio server directly
node mcp-stdio.js

# The server will wait for MCP protocol messages on stdin

项目结构

├── src/
│   └── index.ts           # Cloudflare Workers MCP server
├── mcp-stdio.js          # Local stdio MCP server
├── package.json          # Dependencies and scripts
├── wrangler.jsonc        # Cloudflare Workers config
├── CLAUDE.md            # Claude-specific documentation
└── README.md            # This file

内容源

服务器使用两个不同的内容源，分别进行5分钟缓存：

工具内容(https://halans.com/llms-full.txt)

由search_content、get_section、get_full_content和get_content_summary工具使用：

• 完整的博客内容和文章全文
• 技术文件和详细说明
• 全面的项目描述
• 完整的会议记录和见解

资源内容(https://halans.com/llms.txt)

由可浏览资源使用(halans://content等等）：

• 按时间顺序排列的文章列表（年份降序）
• 文章标题、发表日期和网址
• 结构化元数据，便于浏览
• 内容摘录和摘要

使用MCP检查员进行本地测试

npx @modelcontextprotocol/inspector

连接到克劳德桌面

用于本地标准服务器

将此添加到您的Claude Desktop MCP配置中：

{
  "mcpServers": {
    "halans-content": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-stdio.js"],
      "env": {}
    }
  }
}

适用于已部署的Workers（带mcp远程）

{
  "mcpServers": {
    "halans-content": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your-worker-url.workers.dev/sse"
      ]
    }
  }
}

连接到Cloudflare AI游乐场

对于已部署的Workers，您可以使用Cloudflare AI Playground测试MCP服务器：

1. 首选https://playground.ai.cloudflare.com/
2. 输入您部署的MCP服务器URL(your-worker-url.workers.dev/sse)
3. 直接测试内容查询工具

运行MCP检查器

npx @modelcontextprotocol/inspector@latest

部署定制

自定义域（可选）

要将自定义域与Cloudflare Worker一起使用，请执行以下操作：

1. 在Cloudflare仪表板中添加自定义域
2. 更新 wrangler.jsonc 使用您的域名：

{
  "routes": [
    {
      "pattern": "mcp.yourdomain.com/*",
      "custom_domain": true
    }
  ]
}

环境变量

添加配置环境变量：

# Set environment variables
npx wrangler secret put API_KEY
npx wrangler secret put CONTENT_URL

然后在Worker中访问它们：

// In src/index.ts
const toolsContentUrl = env.TOOLS_CONTENT_URL || "https://halans.com/llms-full.txt";
const resourcesContentUrl = env.RESOURCES_CONTENT_URL || "https://halans.com/llms.txt";

故障排除

常见问题

1. MCP连接失败

- 确保服务器URL正确 - 检查Worker是否已部署且可访问 - 验证克劳德桌面配置

1. 内容获取错误

- 检查是否 https://halans.com/llms-full.txt 和 https://halans.com/llms.txt 可访问 - 从Worker验证网络连接 - 监控Cloudflare日志以查找获取错误

1. 开发服务器问题

- 跑 npm install 确保安装了依赖项 - 检查Node.js版本兼容性（建议使用v18+） - 使用 npm run type-check 识别TypeScript错误

监控

• 在Cloudflare仪表板中查看Worker日志
• 使用 wrangler tail 用于实时日志监控
• 在Claude Desktop中监视MCP服务器日志

定制

要添加自己的工具，请执行以下操作：

• Stdio服务器：编辑 mcp-stdio.js 并添加新的工具处理程序
• Workers服务器：编辑 src/index.ts 并在中添加工具 init() 方法

示例：添加新工具

// In src/index.ts or mcp-stdio.js
this.server.tool(
    "new_tool",
    {
        parameter: z.string().describe("Tool parameter")
    },
    async ({ parameter }) => {
        // Tool implementation
        return {
            content: [{ type: "text", text: `Result: ${parameter}` }]
        };
    }
);