经办人-mcp模板

Name: 经办人-mcp模板
Author: dyeoman2

作者：dyeoman22 星标更新：2025-06-05

安装使用来源：spider==github.com

项目介绍

Clerk MCP Server 模板

一个用于构建带有 Clerk 认证的 Model Context Protocol (MCP) 服务器的生产就绪模板，基于 Cloudflare Workers。此模板提供了创建与现有 Clerk 驱动应用程序集成的安全认证 MCP 工具所需的一切。

特性

✅ Clerk 认证集成 - 完整的 OAuth 2.0 流程与 Clerk
✅ Cloudflare Workers - 全球分布的无服务器边缘计算
✅ 持久对象 - 持久的 MCP 会话状态管理
✅ KV 存储 - 临时 OAuth 会话存储
✅ 安全性 - HMAC 签名的状态参数和自动令牌刷新
✅ TypeScript - 整个代码库中的完整类型安全
✅ 示例工具 - 准备使用的示例 MCP 工具
✅ 开发工具 - ESLint、Prettier 和 MCP Inspector 集成

为什么选择这个模板？

这个模板连接了您的现有 Clerk 认证应用程序与 Claude AI 通过 MCP 工具。非常适合：

SaaS 应用程序：给 Claude 访问您的用户数据和业务逻辑
客户服务：让 Claude 在适当的用户上下文中查询您的系统
数据分析：提供 Claude 对您的 API 的认证访问
工作流自动化：创建安全的、特定用户的自动化

快速开始

1. 前提条件

Node.js 22.x 或更高版本
一个具有 API 密钥的 Clerk 账户
一个启用了 Workers 的 Cloudflare 账户
使用 Clerk 进行认证的现有应用程序

2. 使用此模板

git clone https://github.com/your-username/clerk-mcp-template.git my-mcp-server
cd my-mcp-server
npm install

3. 配置环境变量

复制示例环境文件：

cp .dev.vars.example .dev.vars

更新 .dev.vars 文件中的 Clerk 密钥和应用 URL：

CLERK_SECRET_KEY=sk_test_your_actual_clerk_secret_key
CLERK_PUBLISHABLE_KEY=pk_test_your_actual_clerk_publishable_key
APP_URL=https://your-app.com

重要：APP_URL 应指向您现有的 Clerk 认证应用程序，在该应用程序中您将实现 MCP 认证流程。

4. 创建 KV 命名空间

为 OAuth 会话存储创建一个 KV 命名空间：

wrangler kv:namespace create "OAUTH_KV"

在 wrangler.jsonc 中更新生成的命名空间 ID。

5. 更新配置

wrangler.jsonc：

将 name 从 "your-mcp-server" 更改为所需的 worker 名称
更新 KV 命名空间 ID 为上面生成的 ID

src/index.ts：

更新 McpServer 构造函数中的服务器名称和版本
替换示例工具为您自己的工具（参见下面的示例）

6. 开始开发

npm run dev

服务器将在 http://localhost:8788 上可用

架构

graph TB
    A[MCP 客户端] --> B[Cloudflare Worker]
    B --> C[OAuth 提供者]
    C --> D[Clerk 认证]
    B --> E[持久对象]
    B --> F[KV 存储]
    B --> G[您的 API]

    E --> H[MCP 会话状态]
    F --> I[OAuth 会话]
    D --> J[用户认证]
    G --> K[您的应用程序数据]

认证流程

MCP 客户端连接 到 /sse 端点
OAuth 重定向 到 /authorize 端点
用户认证 通过 Clerk（您实现这一部分）
令牌交换 在 /callback 端点
会话创建 在持久对象中
MCP 工具 在认证上下文中变得可用

与您的应用程序集成

第一步：添加 MCP 认证路由

在您的现有 Clerk 应用程序中创建一个认证路由 /auth/mcp。此路由处理由 MCP 服务器发起的 OAuth 流程。

React Router v7（框架模式）示例

此示例展示了如何在框架模式下（以前称为 Remix）与 React Router v7 集成，但您可以将其适应于 Next.js、Express 或任何框架。

app/routes/auth.mcp.tsx：

import { createClerkClient } from '@clerk/express'
import { redirect, type LoaderFunctionArgs } from 'react-router'

export async function loader({ request }: LoaderFunctionArgs) {
	const url = new URL(request.url)
	const state = url.searchParams.get('state')
	const callbackUrl = url.searchParams.get('callback_url')
	const clientName = url.searchParams.get('client_name')

	if (!state || !callbackUrl) {
		throw new Error('缺少必需的参数')
	}

	// 获取已认证用户的会话令牌
	const clerkClient = createClerkClient({
		secretKey: process.env.CLERK_SECRET_KEY,
		publishableKey: process.env.CLERK_PUBLISHABLE_KEY,
	})

	const clerkAuth = (await clerkClient.authenticateRequest(request)).toAuth()
	const sessionToken = await clerkAuth?.getToken()

	if (!sessionToken) {
		// 如果未认证，则重定向到登录页面
		const signInUrl = new URL('/sign-in', request.url)
		signInUrl.searchParams.set('redirect_url', request.url)
		return redirect(signInUrl.toString())
	}

	// 重定向回 MCP 服务器并携带令牌
	const redirectUrl = new URL(callbackUrl)
	redirectUrl.searchParams.set('clerk_token', sessionToken)
	redirectUrl.searchParams.set('state', state)

	return redirect(redirectUrl.toString())
}

// 可选：添加组件以显示同意屏幕
export default function McpAuth() {
	return (
		<div className="max-w-md mx-auto mt-8 p-6 bg-white rounded-lg shadow-md">
			<h1 className="text-xl font-bold mb-4">授权 MCP 访问</h1>
			<p className="text-gray-600 mb-4">
				Claude AI 正请求访问您的账户数据。
			</p>
			<p className="text-sm text-gray-500">
				这将自动重定向您...
			</p>
		</div>
	)
}

第二步：创建 API 端点

在您的应用程序中添加受保护的 API 端点，MCP 服务器可以使用认证请求调用这些端点。

app/routes/api.users.tsx：

import { createClerkClient } from '@clerk/express'
import { json, type LoaderFunctionArgs } from 'react-router'

export async function loader({ request }: LoaderFunctionArgs) {
	try {
		const clerkClient = createClerkClient({
			secretKey: process.env.CLERK_SECRET_KEY,
			publishableKey: process.env.CLERK_PUBLISHABLE_KEY,
		})

		// 验证请求是否已认证
		const clerkAuth = await clerkClient.authenticateRequest(request)
		const userId = clerkAuth.toAuth()?.userId

		if (!userId) {
			return json({ error: '未经授权' }, { status:  401 })
		}

		// 您的业务逻辑在此处
		const users = await getUsersForCurrentUser(userId)

		return { users }
	} catch (error) {
		return json({ error: '内部服务器错误' }, { status: 500 })
	}
}

第三步：自定义 MCP 工具

替换 src/index.ts 中的示例工具：

// 自定义工具示例
this.server.tool(
	'getUsers',
	'从您的应用程序获取所有用户',
	{},
	this.requireAuth(async () => {
		const users = await this.makeApiRequest('api/users')

		return {
			content: [
				{
					type: 'text',
					text: `找到 ${users.length} 个用户:\n${JSON.stringify(users, null, 2)}`,
				},
			],
		}
	}),
)

配置参考

环境变量

变量	描述	必需
`CLERK_SECRET_KEY`	您的 Clerk 秘密密钥	✅
`CLERK_PUBLISHABLE_KEY`	您的 Clerk 发布密钥	✅
`APP_URL`	您的应用程序 URL	✅

向 src/types.ts 中的 Env 接口添加您自己的应用程序特定环境变量。

Clerk JWT 模板

在您的 Clerk 控制面板中创建一个 JWT 模板以生成令牌：

在您的 Clerk 控制面板中转到 JWT 模板
创建一个新的模板（例如，“mcp-server”）
更新 src/index.ts 中的模板名称：

const token = await getToken(
	// ... 令牌管理器
	(this as any).env.CLERK_SECRET_KEY,
	'your-template-name', // 更新此内容
)

开发

可用脚本

npm run dev        # 启动开发服务器
npm run deploy     # 部署到 Cloudflare Workers
npm run inspect    # 启动 MCP Inspector
npm run lint       # 运行 ESLint + 格式化
npm run typecheck  # 运行 TypeScript 类型检查
npm run validate   # 运行类型检查 + 校验

使用 MCP Inspector 测试

启动开发服务器：npm run dev
打开 MCP Inspector
设置传输类型为 SSE
连接到 http://localhost:8788/sse
完成认证流程
测试您的工具

部署

1. 设置生产密钥

wrangler secret put CLERK_SECRET_KEY
wrangler secret put CLERK_PUBLISHABLE_KEY
wrangler secret put APP_URL

2. 创建生产 KV 命名空间

wrangler kv:namespace create "OAUTH_KV" --env production

更新生产 KV 命名空间 ID 在 wrangler.jsonc 中。

3. 部署和配置

npm run deploy

将部署的服务器添加到 Claude Desktop MCP 配置中：

{
	"mcpServers": {
		"my-app": {
			"command": "npx",
			"args": [
				"@modelcontextprotocol/server-remote",
				"https://your-mcp-server.your-subdomain.workers.dev/sse"
			]
		}
	}
}

项目结构

clerk-mcp-template/
├── src/
│   ├── index.ts      # 主 MCP 服务器类和工具
│   ├── auth.ts       # OAuth 认证处理器
│   ├── clerk.ts      # Clerk 认证实用工具
│   ├── utils.ts      # 实用函数（HMAC、日志记录等）
│   └── types.ts      # TypeScript 类型定义
├── wrangler.jsonc    # Cloudflare Worker 配置
├── package.json      # 依赖项和脚本
├── tsconfig.json     # TypeScript 配置
├── eslint.config.js  # ESLint 配置
├── .dev.vars         # 开发环境变量
└── README.md         # 本文件

安全注意事项

OAuth 2.0 确保安全的认证流程
HMAC 签名 保护状态参数不被篡改
自动令牌刷新 处理会话过期
会话清理 删除过期的 OAuth 会话
安全头 包括正确的 CORS 和认证头

故障排除

常见问题

认证失败：

验证 Clerk API 密钥是否正确
确保您的认证路由已实现
检查 Clerk 控制面板中是否存在 JWT 模板

KV 命名空间错误：

验证 wrangler.jsonc 中的命名空间 ID
确保命名空间已创建并绑定

工具无法正常工作：

检查用户是否已认证
验证 API 端点是否正确
查看 Cloudflare Workers 日志

调试

# 查看实时日志
wrangler tail

# 检查部署状态
wrangler deployments list

# 本地调试测试
npm run dev

贡献

分叉此仓库
创建一个特性分支：git checkout -b feature/amazing-feature
提交您的更改：git commit -m '添加神奇的功能'
推送到分支：git push origin feature/amazing-feature
打开一个拉取请求

资源

许可证

MIT 许可证 - 详情见 LICENSE 文件。