🚀 Civicnet MCP Server – Model Context Protocol

🚀 Civicnet MCP 服务 – Model Context Protocol

欢迎使用官方开源 MCP 服务。
这是 Konstellation 和 CivicNet 联邦式公民基础设施的核心——一个模块化、以原则为导向的服务，用于运行本地、可信且具有 Agent 能力的社区 AI。

---

🧭 什么是 MCP 服务？

MCP 服务为 CivicNet/Konstellation 网格中的**邻里、城市或组织级“节点”**提供支持。每个节点都能：

• 接收并验证本地数据（GIS、政策、社区故事、公共记录）
• 托管并编排具有 Agent 能力的模型（推理、自我审计、模拟、角色扮演等）
• 对每个查询和输出应用公民原则（公平、真实、隐私、透明）
• 为仪表板、GIS 客户端和外部合作伙伴发布安全且有文档说明的 API
• 与其他 MCP 节点联邦协作，共享知识，同时保持本地控制权

为什么要这样做？
让每个社区都能拥有、治理并持续改进自己的公民智能——没有黑箱、没有供应商锁定，也没有隐性偏见。

---

🌌 主要功能

• 不受大模型限制： 可接入任何现代语言模型（OpenAI、Anthropic、开源模型）
• 不受云平台限制： 可部署在你的云环境、本地服务器、边缘设备或本地设备上
• 原则库： 以代码定义、审计和演进社区原则
• 模块化 Agent 逻辑： 支持思维链、自我反思、角色模拟、多 Agent 辩论等
• 数据管理： 为本地、开放和联邦式公民数据提供细粒度连接器
• 支持模拟： 运行“假设”场景和参与式模拟
• 完整审计跟踪： 记录并支持审查每项输出、Agent 步骤和数据来源
• Docker 化： 便于设置容器，可在本地或分布式环境中运行

---

🗃 目录概览

文件夹	用途
src/agents	Agent 模型（推理、对齐、模拟）
src/api	用于查询、数据和工具的 REST/GraphQL API
src/principles	原则库（YAML/JSON + 逻辑）
src/data	数据接入、验证和连接器
src/prompts	提示词模板和场景脚本
src/simulation	模拟和场景建模逻辑
src/utils	日志、审计和辅助函数
config/	节点配置、启用的功能、.env 模板
scripts/	开发、测试和迁移脚本
tests/	单元测试和集成测试

---

⚡️ 快速开始（本地 Docker Compose）

1. 克隆代码库：

   git clone https://github.com/PublikPrinciple/civicnet-mcp-server.git
   cd civicnet-mcp-server
   

2. 复制并编辑环境变量：

   cp config/.env.example .env
   # Edit .env with your API keys, DB, LLM settings, etc.
   

3. 启动 MCP 服务（以及可选的数据服务）：

   docker-compose up --build
   

4. 查看 API 文档：

   • 前往 http://localhost:4000/docs（默认使用 Swagger/OpenAPI）

---

🛠️ 核心概念

原则库

• 所有输出都会经过检查、过滤或改写，以符合社区的核心原则（例如“确保公平”“避免伤害”“注明来源”）。
• 在 /src/principles/ 中通过 YAML/JSON 更新原则。

Agent 与 Agent 逻辑

• 思维链 Agent： 采用逐步推理，以提高透明度
• 自我反思 Agent： 检查自身偏见、逻辑和合规性
• 角色模拟 Agent： 模拟辩论（规划者与居民之间）、专家小组讨论或历史视角
• 多 Agent 协作： 支持场景测试、参与式预算编制和红队测试
• 每个 Agent 的逻辑都采用模块化设计，并可组合使用（参见 /src/agents/）。

数据层

• 用于 GIS、人口普查、本地 CSV、API 等的连接器
• 用于隐私保护和数据卫生的验证/脱敏步骤
• 联邦协作： 与可信节点共享/选择性共享（需主动选择）

提示词与场景模板

• 所有 Agent 推理均由提示词模板驱动（参见 /src/prompts/）
• 可自行编写模板，也可使用内置的公民案例研究和模拟模板

模拟

• 使用真实和合成数据模拟“假设”情景（住房、气候、预算等）
• 输出具有交互性，并经过原则审计

---

🔑 示例用例

• 生成“达勒姆住房危机”案例研究，包含地图、时间线和公平性分析，可供 GIS 使用和公众审阅
• 通过社区 Agent 之间的角色扮演辩论，支持参与式预算模拟
• 发布通俗易懂、符合原则的数据 API，供本地仪表板使用
• 审计所有输出中的偏见、错误和社区原则（含日志和反馈）
• 与其他社区／城市建立联邦协作，以比较、重组和改进本地分析

---

🧑‍💻 面向开发者

• **语言：**默认使用 TypeScript/Node.js，路线图中计划兼容 Python Agent
• **贡献：**有关分支、代码风格和原则对齐 PR 检查，请参阅 CONTRIBUTING.md
• **测试：**运行 npm test（Jest），或使用 docker-compose -f docker-compose.test.yml up 运行全部测试

---

🏛️ 面向公民数据管理者

• **原则驱动的治理：**编辑 /src/principles/ 以更新节点的价值观
• **日志与审计：**每个回答均可追溯（谁提出了请求、使用了哪些数据和 Agent、进行了哪些检查）
• **开放 API：**基于 MCP 服务的端点，构建自己的 GIS 客户端、仪表板或移动应用

---

🔒 安全与隐私

• 未经明确的原则驱动授权并进行脱敏，绝不会共享或暴露敏感数据
• 每个节点均在沙盒中运行；联邦协作始终需要主动选择，并且可审计

---

🌍 联邦协作与星群

• **支持 Konstellation：**此服务专为联邦协作而设计——可与其他社区、城市或地区发布／共享洞见，同时完整保留本地治理和隐私
• **联邦查询：**支持比较（例如，“显示所有社区的驱逐率”）

---

📖 文档与社区

• 完整文档位于 /docs/ 或 civicnet.org/docs 链接
• 加入 Discord 上的 #mcp-server 频道，获取支持并参与讨论

---

📝 许可证

AGPL 2.0 – 开放、可重组，由社区驱动
详情请参阅 LICENSE

---

✨ 开始构建公民基础设施的未来！

---

📘 Swagger/OpenAPI 配置（API 端点概览）

将以下内容添加到 /src/api/routes.ts（示例）：

import express from 'express'; import swaggerUi from 'swagger-ui-express'; import YAML from 'yamljs';

const router = express.Router(); const swaggerDocument = YAML.load('./config/swagger.yaml');

router.use('/docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument)); export default router;

swagger.yaml 入门示例：

openapi: 3.0.0 info: title: MCP Server API version: 1.0.0 paths: /api/analyze: post: summary: Analyze civic query using agentic logic requestBody: required: true content: application/json: schema: type: object properties: query: type: string context: type: object responses: '200': description: Analysis complete