MCP服务器路径
A. 模型上下文协议 （MCP）服务器，它公开 路径 健康细分平台作为结构化工具。Pathways提供以女性为中心的数据和见解，帮助全球卫生组织设计有针对性的干预措施。
它做什么
该服务器连接到参数化Pathways Strapi CMS API，并提供工具、资源和提示，让Claude（或任何MCP客户端）探索人口细分数据。
工具-数据（Strapi API）
这些工具实时查询Pathways Strapi后端并返回结构化数据。
| 工具 | 说明 |
|---|---|
list_segmentations | 发现可用的国家研究（塞内加尔、肯尼亚、尼日利亚等） |
get_segmentation | 特定研究的完整细节和片段 |
list_segments | 按脆弱程度或阶层（城市/农村）过滤细分市场 |
get_segment_profile | 按主题/领域提供指标的综合“这些女性是谁？”视图 |
get_segment_metrics | 可按健康主题筛选的细分市场定量指标 |
search_variables | 按名称、主题、域或数据类型搜索指标 |
list_themes_and_domains | 健康主题和脆弱性领域参考列表 |
list_regions | 一个国家的次国家区域 |
get_geographic_distribution | 各地区细分市场的地理分布 |
工具——上下文（静态）
这些工具从捆绑包中返回静态内容 .md 文件——分析框架、伦理准则和定性生活故事。它们塑造了人工智能对Pathways数据的推理方式。
| 工具 | 说明 |
|---|---|
load_lens | 六域漏洞框架——在任何分段分析之前加载 |
load_interventions | 干预设计框架（层次、原型、变革逻辑） |
load_ethics | 数据使用、通信和人工智能推理的道德护栏 |
load_awihs_kenya | 肯尼亚的定性生活故事（塔纳河、图尔卡纳、内罗毕） |
load_awihs_northern_nigeria | 尼日利亚北部的定性生活故事 |
load_awihs_bihar_india | 来自印度比哈尔邦的定性生活故事 |
资源
资源应提供框架和定性背景，指导AI客户端如何解释Pathways数据。它们将Pathways的镜头和框架注入到对话中。
每个资源都注册为MCP资源（URI可通过以下方式寻址 pathways://…)以及作为一个可调用的工具（见上文）。鉴于并非所有MCP客户端都使用资源，因此双重注册有助于我们确保任何客户端都可以在需要时将这些框架加载到上下文中。
| 资源 | URI | 描述 |
|---|---|---|
load_lens | pathways://lens | 六域漏洞框架——在任何分段分析之前加载 |
load_interventions | pathways://interventions | 干预设计框架（层次、原型、变革逻辑） |
load_ethics | pathways://ethics | 数据使用、通信和人工智能推理的道德护栏 |
load_awihs_kenya | pathways://awihs_kenya | 肯尼亚的定性生活故事（塔纳河、图尔卡纳、内罗毕） |
load_awihs_northern_nigeria | pathways://awihs_northern_nigeria | 尼日利亚北部的定性生活故事 |
load_awihs_bihar_india | pathways://awihs_bihar_india | 来自印度比哈尔邦的定性生活故事 |
先决条件
- Python 3.10+
- Pathways API令牌（Strapi CMS的只读承载令牌）
安装
cd pathways-mcp-server
python3 -m venv .venv
source .venv/bin/activate
pip install -e .配置
复制示例env文件并添加您的令牌：
cp .env.example .env
# Edit .env and set PATHWAYS_API_TOKEN| 变量 | 描述 |
|---|---|
PATHWAYS_API_TOKEN | Strapi（请只读）API代币 |
PATHWAYS_API_URL | strapi API基本URL |
服务器通过以下方式进行通信 stdio 使用MCP协议。要交互式测试，您可以使用MCP检查器：
npx @modelcontextprotocol/inspector pathways-mcp 与Claude Desktop一起使用
将此添加到 ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"pathways": {
"command": "
/pathways-mcp-server/.venv/bin/python",
"args": ["-m", "pathways_mcp.server"],
"cwd": "
/pathways-mcp-server",
"env": {
"PATHWAYS_API_TOKEN": "",
"PATHWAYS_API_URL": "https://api.staging.withpathways.org"
}
}
}
}项目结构
pathways-mcp-server/
├── pyproject.toml
├── requirements.txt
├── .env.example
├── .gitignore
├── README.md
└── src/
└── pathways_mcp/
├── __init__.py
├── __main__.py # python -m entry point
├── server.py # FastMCP server + tool/resource/prompt registration
├── api.py # Strapi API client (httpx, auth, pagination)
├── prompts.py # Prompt definitions (read from prompts/*.md)
├── prompts/
│ └── segment_deep_dive.md
├── resources.py # Resource definitions (read from resources/*.md)
├── resources/
│ ├── lens.md
│ ├── interventions.md
│ ├── ethics.md
│ ├── awihs_kenya.md
│ ├── awihs_northern_nigeria.md
│ └── awihs_bihar_india.md
└── tools/
├── __init__.py
├── segmentations.py
├── segments.py
├── metrics.py
├── variables.py
├── reference.py
└── geography.pyAPI客户端(api.py)
这是最重要的基础设施文件。它处理所有HTTP通信。
这 StrapiClient 类
实例化时，它读取两个环境变量——现在都是必需的：
PATHWAYS_API_TOKEN--Bearer令牌（如果丢失，则立即引发错误）PATHWAYS_API_URL--基本URL（如果缺少，则立即引发错误；没有默认回退）
self._headers = {"Authorization": f"Bearer {token}"}每个请求都包含此标头，Strapi使用此标头来验证访问。
fetch_collection --一页结果
这是主要的方法。它
- 构建查询字符串参数（筛选器、分页、填充、字段）
- 使用以下命令发出异步HTTP GET请求
httpx - 返回解析后的JSON
async with httpx.AsyncClient(...) as client:
resp = await client.get(url, params=params)
resp.raise_for_status()
return resp.json()resp.raise_for_status() 检查HTTP状态代码。如果服务器返回4xx或5xx错误，它会立即引发Python异常，而不是默默地返回损坏的数据。在调用之前，代码还会检查特定代码以给出可操作的错误消息：
if resp.status_code == 403:
raise RuntimeError("Access denied... Check your PATHWAYS_API_TOKEN.")
if resp.status_code == 404:
raise RuntimeError(f"Endpoint '{endpoint}' not found on the Strapi API.")403表示令牌错误或已过期。404表示端点路径本身不存在——通常是集合名称中的拼写错误。
fetch_all --自动分页
有些工具需要所有记录，而不仅仅是一页。 fetch_all 电话 fetch_collection 在循环中，在每次迭代中推进页码：
while True:
result = await self.fetch_collection(..., page=page, ...)
data = result.get("data", [])
all_data.extend(data)
page_count = result["meta"]["pagination"]["pageCount"]
if page >= page_count or len(all_data) >= max_records:
break
page += 1Strapi告诉你有多少页面存在于 meta.pagination.pageCount 现场。当您获取最后一页或点击时，循环停止 max_records （如果数据意外增长，可以防止获取数千条记录的安全上限）。
这是由以下人员使用的 get_segment_profile 对于其指标获取和变量获取，两者都可以是非常大的数据集。
这 populate 参数——Strapi关系是什么
在关系数据库中，a 外键 是指一个表只存储另一个表中记录的ID，而不是完整数据。例如，a metrics 记录存储a variable_id: 42 而不是复制变量的所有字段。
斯特拉皮的工作原理是一样的。默认情况下，当你获取一个指标时，你会得到：
{ "id": 1, "percentage": 0.34, "variable": null }要获取嵌入在响应中的实际变量数据，您可以传递 populate:
populate=["variable", "categorical_level"]Strapi然后在幕后执行数据库JOIN并返回：
{
"id": 1,
"percentage": 0.34,
"variable": { "code": "fp.mod.use", "name_en": "Modern FP use", ... },
"categorical_level": { "name_en": "Yes", ... }
}如果没有填充，工具代码将不得不对每个变量进行单独的API调用，这将是数百个额外的请求。Populate一次性将它们全部取出。
单一模式
_client: StrapiClient | None = None
def get_client() -> StrapiClient:
global _client
if _client is None:
_client = StrapiClient()
return _client客户端创建一次，并在所有工具调用中重用。这避免了在每次请求时重新读取环境变量和重新分配内存。
RESPONSE_CHAR_LIMIT
设置为25000个字符。所有工具响应在返回给Claude之前都会被截断到此长度：
return json.dumps(output, indent=2)[:RESPONSE_CHAR_LIMIT]这是一个实用的防护措施：太大的MCP响应可能会导致AI客户端出现问题或达到上下文限制。
______________________________________________________________________