City Code MCP

城市代码MCP

Docker使用

您可以在Docker容器中运行City Code MCP。此选项包括预装的Node.js、Ollama和nomic嵌入文本模型。

先决条件

• Docker已安装

构建Docker镜像

从项目根：

npm run docker-build

这将在本地构建Docker镜像，如下所示 city-code-mcp:latest.

如果你从Docker Hub拉取而不是在本地构建，请使用：

docker pull jtvanwage/city-code-mcp:latest

通过Docker运行MCP

您可以在Docker中使用环境变量运行MCP服务器：

docker run --rm -p 11434:11434 -e CITY_NAME="EagleMountain-Utah" city-code-mcp:latest

如果使用Docker Hub镜像标签，请运行：

docker run --rm -p 11434:11434 -e CITY_NAME="EagleMountain-Utah" jtvanwage/city-code-mcp:latest

可选：创建一个本地别名，以便两个名称都能使用：

docker tag jtvanwage/city-code-mcp:latest city-code-mcp:latest

您可以设置其他环境变量：

• CITY_NAME （必填）：代码下逗号分隔的城市文件夹/
• OLLAMA_EMBED_MODEL （可选）：默认为nomic嵌入文本
• OLLAMA_WARMUP （可选）：默认为true

MCP服务器将启动，Ollama将在 http://localhost:11434 在容器内。

MCP客户端配置示例（Docker）

{
	"command": "docker",
	"args": [
		"run", "--rm", "-e", "CITY_NAME=EagleMountain-Utah", "jtvanwage/city-code-mcp:latest"
	]
}

______________________________________________________________________

代码下城市代码文件的语义搜索MCP//使用Ollama嵌入的目录。

先决条件

• Node.js 18+
• Ollama已安装并正在运行
• 提取的嵌入模型（默认：nomic嵌入文本）

环境

• CITY_NAME（必填）：接受代码/下以逗号分隔的城市文件夹列表（例如，EagleMountain Utah、SaratogaSprings Utah）。所有指定的城市都将被加载并索引以进行语义搜索。
• OLLAMA_HOST（可选）：默认为http://localhost:11434
• OLLAMA_EMBED_MODEL（可选）：默认为nomic嵌入文本
• OLLAMA_WARMUP（可选）：默认为true，在启动时加热索引

构建

安装依赖项并编译TypeScript：

npm install
npm run build

编译后的输出是项目根目录中的index.js，因为 Tsconflict.儿子 未指定outDir。

可选清洁步骤：

npm run clean

运行（MCP stdio）

通过stdio启动MCP服务器：

npm run start

这将启动中定义的服务器 index.ts 并使用stdio传输。

MCP客户端配置（stdio）

MCP客户端配置条目示例：

{
	"command": "node",
	"args": ["/path/to/mcp/index.js"],
	"env": {
		"CITY_NAME": "EagleMountain-Utah",
		"OLLAMA_HOST": "http://localhost:11434",
		"OLLAMA_EMBED_MODEL": "nomic-embed-text"
	}
}

MCP工具名称为 semanticSearchCityCode，并且它接受 query （必填）以及 topK （可选，1-20）。

运作原理

• 读取代码下的所有.txt文件//（CITY_NAME为必填项）
• 按行将文本分块，并设定最大大小目标
• 通过Ollama创建嵌入
• 在.cache/ollama嵌入项下缓存嵌入项。\.json
• 通过MCP stdio公开语义搜索工具

MCP工具

工具名称：语义搜索城市代码

输入：

• 查询：字符串（必填）
• topK：整数（1-20，可选）

输出：包含文件名、行范围、分数和文本的匹配块的JSON列表。

备注

• 如果更改OLLAMA_EMBED_MODEL，缓存将自动重建。
• 启动时，服务器在后台预热索引（使用OLLAMA_WARMUP=false禁用）。
• 如果禁用预热，则第一个查询将构建索引；后续查询使用缓存。
• CITY_NAME为必填项；如果文件夹丢失，则错误会在code/下列出可用的城市文件夹。

使用说明

您可以通过两种方式运行MCP：

1.每个城市一个MCP实例（推荐）

• 将CITY_NAME设置为单个城市文件夹（例如，犹他州鹰山）。
• 每个MCP实例只会搜索并返回该城市的结果。
• 这避免了混淆，并使结果具有城市特定性。

2.多个城市的一个MCP实例

• 将CITY_NAME设置为逗号分隔的列表（例如，EagleMountain Utah、SaratogaSprings Utah）。
• 结果可能来自任何负载城市。
• 用户应在查询中包含城市名称 （例如，“鹰山犬条例”）以获得特定城市的结果。
• 适用于跨城市比较，但需要明确的查询。