MCP服务器：Nominatim属性信息示例
此存储库包含一个最小的MCP（模型连接器协议）服务器，用于演示如何使用OpenStreetMap Nominatim API向语言模型暴露属性/位置查找功能。此示例有意设计得小巧且本地化，以便轻松使用Claude桌面应用程序（或其他MCP客户端）运行。
概述
MCP服务器通过将语言模型与数据源和服务连接起来，扩展了语言模型的功能。它们提供了三种主要的原语（或基本功能）：
- 资源（客户端控制）：在请求时暴露数据以用作上下文。用于被动数据访问。
- 工具（模型控制）：提供模型可调用的可执行功能，用于获取或转换数据。
- 提示（用户控制）：向用户提供可重用的提示和工作流。
这个示例专注于一个单一工具， get_property_info，它使用Nominatim API查找地址/地名，并返回基本位置信息（显示名称、坐标和地点类型）。
为什么选择Nominatim？
- 非商业用途可免费使用（需遵守Nominatim使用政策）。
- 简单查询无需API密钥。
- 返回关于地点和坐标的结构化、机器友好的JSON数据。
重要提示：Nominatim 实施速率限制，并要求提供描述性的 User-Agent 请求头。请参阅下面的使用说明。
内容
mcp-server-property.py— 本示例中使用的MCP服务器入口点。pyproject.toml— 项目元数据和依赖项。README.md— 这个文件。
要求
- 一个 Claude.ai 账户以及 Claude 桌面应用程序（用于 MCP 客户端测试），或任何具备 MCP 功能的客户端。
- 一个代码编辑器（推荐使用VS Code）。
- 一个Python 3.10+的环境。
uv（可选）或者使用标准的虚拟环境（venv）进行环境管理。
快速设置
- 在您的编辑器中打开项目文件夹。
- 创建并激活一个虚拟环境（或使用
uv（如果你更喜欢）：
python -m venv .venv
source .venv/bin/activate- 将运行时依赖项安装到当前活动环境中：
pip install "mcp[cli]" httpx注释：
- 如果你使用
uv（在一些MCP材料中提到的基于Rust的Python环境管理器），你也可以运行uv venv和uv add "mcp[cli]" httpx。
服务器
示例服务器初始化了一个 FastMCP 实例化并暴露一个单一工具：
get_property_info(address: str) -> str— 举头看address使用Nominatim，并返回一个简短、易于人类阅读的字符串，其中包含显示名称、地点类型、纬度和经度。
关键的实施细节在于 mcp-server-property.py：
- 用途
httpx.AsyncClient执行HTTP请求。 - 发送一个
User-Agent标题（对于遵守Nominatim政策至关重要）。 - 将结果限制为最佳匹配项（
limit=1）。
运行MCP服务器
以开发者模式启动服务器（如果可用，这还将运行MCP检查器）：
mcp dev mcp-server-property.py或者直接运行服务器以使用stdio传输（适用于通过stdio连接的MCP客户端）：
python mcp-server-property.py当运行时，服务器注册了 get_property_info 工具。在MCP检查器或您的MCP客户端中，使用地址字符串调用该工具，例如：
示例输入：
221B Baker Street, London预期输出（工具返回的用户友好字符串）：
🏠 Property Info:
- Address: 221B, Baker Street, Marylebone, London, Greater London, England, NW1 6XE, United Kingdom
- Type: house
- Latitude: 51.523771
- Longitude: -0.158538注：确切的显示名称和地点类型取决于Nominatim的数据集，可能会有所不同。
使用说明和最佳实践
- 请遵守Nominatim的使用政策：不要用快速的自动化请求淹没API。如果您计划频繁调用API，请考虑添加缓存或限制请求速率。
- 提供描述性内容
User-Agent识别您的应用程序（示例设置mcp-property-demo/1.0）。 - 对于高流量或商业用途，建议考虑使用付费的地理编码服务提供商或托管的Nominatim实例。
扩展服务器
- 添加一个
get_location一个工具，用于返回原始的Nominatim JSON数据，以便模型进行后续处理。 - 添加缓存（内存缓存或持久缓存）以避免对同一地址进行重复查找。
- 添加资源以向客户端暴露最近的查询结果或聚合数据。
故障排除
- 如果MCP服务器没有按预期运行，请检查运行服务器的终端以查看堆栈跟踪。
- 确保您的虚拟环境已激活，并且在该环境中已安装所有依赖项。
许可证
这个项目是一个小型示例，仅供学习之用。请随意使用和修改。