AI导哈

认证待办事项管理服务器

一个集成了Civic认证的现代MCP协议服务器，提供安全的用户认证待办事项管理功能，适用于需要用户隔离数据的应用场景。

  • by alt-shreya
  • JavaScript
  • 本地部署
  • 更新于
在 GitHub 查看 alt-shreya/civic-mcp-server

使用说明

公民身份验证MCP服务器

一个现代的模型上下文协议（MCP）服务器，集成了Civic Auth，用于安全、用户身份验证的todo管理。采用最新的MCP SDK模式构建，并具有美丽的shadcn风格的web界面。

🚀 快速开始

1.安装依赖项

npm install

2.配置环境变量

复制示例环境文件：

cp .env.example .env.local

编辑 .env.local 并添加您的Civic Auth凭据：

PORT=3000
NODE_ENV=development
CLIENT_ID=your-civic-client-id-here

3.获取公民授权证书

  1. 访问 Civic Auth仪表板
  2. 创建新应用程序
  3. 复制您的客户ID
  4. 将其添加到您的 .env.local 文件

4.启动服务器

npm start

访问 http://localhost:3000 访问客户端界面！

🏗️ 建筑

此服务器实现了 混合MCP架构 它结合了：

  • 现代MCP SDK：工具注册 McpServer Zod模式
  • HTTP兼容性：用于web客户端集成的直接HTTP处理
  • 公民身份背景：具有身份验证的每个用户MCP服务器实例
  • 类型安全：使用Zod进行完整的TypeScript风格验证
// Modern MCP tool registration
server.tool(
  "add_todo",
  "Add a new todo item for the authenticated user",
  {
    text: z.string().describe("The content of the todo item"),
  },
  async (input) => {
    // Tool implementation with Civic user context
  }
);

🛠️ API终点

公共端点

端点 方法 描述
/ GET Web客户端界面
/health GET 服务器健康检查
/auth-config GET 公民身份验证配置

受保护的端点

端点 方法 描述 需要身份验证
/mcp POST MCP协议端点 ✅ 公民身份持有者令牌

🔧 可用的MCP工具

所有工具都需要有效的Civic Auth身份验证，并对用户特定的数据进行操作：

1。📝 全部添加

{
  "method": "tools/call",
  "params": {
    "name": "add_todo",
    "arguments": {
      "text": "Learn about MCP with Civic Auth"
    }
  }
}

答复：

{
  "content": [
    {
      "type": "text",
      "text": "✅ Todo added: \"Learn about MCP with Civic Auth\" (ID: 1234567890)"
    }
  ]
}

2.📋 列出待办事项

{
  "method": "tools/call",
  "params": {
    "name": "list_todos",
    "arguments": {}
  }
}

答复：

{
  "content": [
    {
      "type": "text",
      "text": "📋 Your todos:\n⏳ Learn about MCP with Civic Auth (ID: 1234567890)\n✅ Complete project setup (ID: 1234567891)"
    }
  ]
}

3.✅ 切换待办事项完成

{
  "method": "tools/call",
  "params": {
    "name": "toggle_todo",
    "arguments": {
      "todoId": "1234567890"
    }
  }
}

答复：

{
  "content": [
    {
      "type": "text",
      "text": "✅ Todo \"Learn about MCP with Civic Auth\" marked as completed"
    }
  ]
}

4.📚 列出可用工具

{
  "method": "tools/list"
}

答复：

{
  "tools": [
    {
      "name": "add_todo",
      "description": "Add a new todo item for the authenticated user",
      "inputSchema": {
        "type": "object",
        "properties": {
          "text": { "type": "string", "description": "The content of the todo item" }
        },
        "required": ["text"]
      }
    }
  ]
}

🧪 测试集成

选项1:Web客户端（推荐）

  1. 启动服务器: npm start
  2. 打开浏览器：导航到 http://localhost:3000
  3. 验证：点击“与Civic连接”（在开发中使用模拟身份验证）
  4. 测试工具：使用漂亮的UI添加、列出和切换待办事项

选项2：API直接测试

# Test with curl (replace token with actual Civic Auth JWT)
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-civic-auth-token" \
  -d '{
    "method": "tools/call",
    "params": {
      "name": "add_todo", 
      "arguments": {"text": "Test todo from API"}
    }
  }'

选项3:MCP客户端集成

连接Claude Desktop或其他MCP客户端：

  1. 添加到Claude桌面配置 (~/Library/Application Support/Claude/claude_desktop_config.json):
{
  "mcpServers": {
    "civic-todos": {
      "command": "node",
      "args": ["path/to/civic-mcp-server/src/index.js"],
      "env": {
        "CLIENT_ID": "your-civic-client-id"
      }
    }
  }
}
  1. 重新启动克劳德桌面 加载MCP服务器

📁 项目结构

civic-mcp-server/
├── src/
│   └── index.js              # Main server with MCP + Civic Auth
├── public/
│   └── index.html           # Beautiful shadcn-inspired client UI
├── test/
│   └── index.test.js        # Test suite
├── scripts/
│   ├── setup.js            # Setup utilities
│   └── test-client.js      # API testing script
├── .env.example            # Environment template
├── .env.local             # Your configuration (create this)
├── package.json           # Dependencies and scripts
└── README.md             # This documentation

🔧 发展

可用脚本

npm start       # Start the server (with auto-reload)
npm test        # Run test suite
npm run setup   # Initial project setup

添加新的MCP工具

  1. 注册该工具 在……里面 createMcpServer():
server.tool(
  "your_tool_name",
  "Tool description for AI",
  {
    param: z.string().describe("Parameter description"),
  },
  async (input) => {
    // Tool implementation with civicUser context
    const userId = civicUser.id;
    // Your logic here...
    return {
      content: [{ type: "text", text: "Tool response" }]
    };
  }
);
  1. 添加工具处理程序 对于HTTP兼容性：
toolHandlers["your_tool_name"] = async (args) => {
  // Same implementation as above
};
  1. 更新工具架构 在……里面 getToolsSchema() 用于工具/列表支持

主要开发特征

  • 🔄 热重新加载：服务器在更改时自动重新启动
  • 📝 综合录井：记录所有MCP请求和用户操作
  • 🛡️ 模拟身份：开发友好的测试身份验证
  • 🎨 现代用户界面：受shadcn启发的测试工具组件
  • 📊 健康监测：内置健康检查和错误处理

🔒 安全功能

  • ✅ 公民身份整合 -基于JWT代币的钱包身份验证
  • ✅ 用户数据隔离 -每个用户的数据完全分开
  • ✅ 输入验证 -所有工具输入均已Zod模式验证
  • ✅ 错误处理 -全面的错误处理和清理
  • ✅ 令牌验证 -在每个请求中验证承载令牌
  • ✅ 无数据泄露 -用户只能访问自己的待办事项
  • ✅ 开发安全 -用于本地开发/测试的模拟身份验证

🚀 生产部署

环境设置

NODE_ENV=production
PORT=3000
CLIENT_ID=your-production-civic-client-id
# Add any additional production variables

安全考虑

  1. JWT验证：用真正的Civic JWT验证替换模拟身份验证
  2. 仅限HTTPS：确保所有流量在生产中使用HTTPS
  3. 环境变量：从不承诺 .env.local 到版本控制
  4. 速率限制：考虑为API端点添加速率限制
  5. 数据库：用持久数据库替换内存存储

🤝 贡献

我们欢迎捐款！以下是如何开始：

  1. 分叉存储库
  2. 创建要素分支: git checkout -b feature/amazing-feature
  3. 进行更改
  4. 添加测试 对于新功能
  5. 确保所有测试通过: npm test
  6. 提交拉取请求

贡献指南

  • 遵循现有的代码样式和模式
  • 为新功能添加全面的测试
  • 针对任何API更改更新文档
  • 尽可能确保向后兼容性
  • 添加适当的错误处理和日志记录

📜 许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

📚 资源和文件

公民身份

模型上下文协议

开发工具

🆘 支持和故障排除

常见问题

Q： 是否出现“未配置CLIENT_ID”错误？
A： 确保您已创建 .env.local 并从仪表板添加了您的Civic Client ID。

Q： 身份验证不起作用？
A： 在开发中，服务器使用模拟身份验证。对于生产，实施适当的Civic JWT验证。

Q： MCP工具未出现在Claude Desktop中？
A： 检查你的 claude_desktop_config.json 文件，并确保到服务器的路径正确。

Q： 收到HTTP 406错误？
A： 这是当前版本中已修复的传输层的一个已知问题。

获取帮助

关于以下问题：

  • 公民身份：检查 公民文件 或联系公民支持
  • MCP协议：参见 MCP文件 或加入社区
  • 本项目：在此存储库中打开一个包含详细信息的问题

内置于❤️ 使用Civic Auth和模型上下文协议

该项目展示了通过MCP标准将基于安全钱包的身份验证与AI工具集成相结合的强大功能。

相关 MCP