市民网-MCP服务器

Name: 市民网-MCP服务器
Author: Publik-Works

作者：Publik-Works2 星标更新：2025-06-05

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

项目介绍

🚀 Civicnet MCP Server – 模型上下文协议

欢迎来到官方开源的MCP服务器。
这是Konstellation & CivicNet联邦市政基础设施的核心——一个模块化、原则驱动的服务器，用于运行本地、可信且具有代理性的社区AI。

🧭 什么是MCP服务器？

MCP服务器为CivicNet/Konstellation网格中的“节点”提供动力，这些节点可以是邻里、城市或组织级别的。每个节点：

摄入并验证本地数据（GIS、政策、社区故事、公共记录）
托管并编排代理模型（推理、自我审计、模拟、角色扮演等）
将市政原则（公平性、真实性、隐私、透明度）应用于每个查询和输出
发布安全、有文档支持的API供仪表板、GIS客户端和外部合作伙伴使用
联邦与其他MCP节点共享知识，同时保持本地控制

为什么？
为了让每个社区能够拥有、治理并不断改进自己的市政智能——没有黑箱操作，没有供应商锁定，没有隐性偏见。

🌌 关键特性

与语言模型无关： 插入任何现代语言模型（OpenAI、Anthropic、开源）
与云无关： 部署在您的云端、本地、边缘或本地设备上
原则仓库： 在代码中定义、审核和演进社区原则
模块化代理逻辑： 支持链式思维、自我反思、角色模拟、多代理辩论等
数据托管： 细粒度连接器用于本地、开放和联邦市政数据
模拟准备： 运行“假设”场景和参与式模拟
完整的审计跟踪： 每个输出、代理步骤和数据源都被记录并可审查
容器化： 容器设置简单，本地或分布式

🗃 目录概述

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

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

克隆仓库：

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

复制并编辑环境变量：

cp config/.env.example .env
# 使用您的API密钥、数据库、LLM设置等编辑.env

启动MCP服务器（加上可选的数据服务）：
```
docker-compose up --build
```
查看API文档：
- 访问http://localhost:4000/docs（默认为Swagger/OpenAPI）

🛠️ 核心概念

原则仓库

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

代理及代理逻辑

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

数据层

连接器用于GIS、人口普查、本地CSV、API等
验证/删除步骤以保护隐私和数据卫生
联邦： 选择性地与受信任的节点分享（需明确同意）

提示及场景模板

所有代理推理都由提示模板驱动（参见/src/prompts/）
编写自己的或使用内置的市政案例研究和模拟模板

模拟

使用真实和合成数据建模“如果……会怎样？”未来（住房、气候、预算等）
输出是交互式的，并经过原则审核

🔑 示例用例

生成一份带有地图、时间线和公平性分析的“达勒姆住房危机”案例研究，准备好供GIS和公众审查
支持一个角色扮演辩论的参与式预算编制模拟
发布一个简洁的语言、原则一致的数据API供本地仪表板使用
审核所有输出以检测偏见、错误和社区原则（附带日志和反馈）
与其他邻里/城市联邦以比较、重组和改进本地分析

🧑‍💻 开发者指南

语言： 默认为TypeScript/Node.js，Python代理兼容性在路线图中
贡献： 查看CONTRIBUTING.md了解分支、代码风格和原则一致性PR检查
测试： npm test（Jest），或运行所有测试docker-compose -f docker-compose.test.yml up

🏛️ 市政数据托管者指南

原则驱动治理： 编辑/src/principles/以更新您节点的价值观
日志&审计： 每个答案都是可追溯的（谁询问了，什么数据，哪些代理，进行了哪些检查）
开放API： 构建您自己的GIS客户端、仪表板或移动应用，基于MCP服务器的端点

🔒 安全与隐私

敏感数据未经明确的原则驱动同意和删除不会被分享或暴露
每个节点都是隔离的；联邦始终是可选的且可审计的

🌍 联邦与星座

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: 使用代理逻辑分析市政查询
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                context:
                  type: object
      responses:
        '200':
          description: 分析完成