内容
# urbandictmcp
**这不是 https://www.urbandictionary.com 的官方 MCP 服务器**
**urbandictmcp 属于 ZMachinery LLC，通过 SHIPMB 拥有**
一个无依赖的 MCP 服务器，允许 MCP 客户端查找 Urban Dictionary 定义。
Urban Dictionary 内容由用户贡献，因此结果可能具有明确、冒犯性、错误或极具互联网特色的内容。
## 功能
`urbandictmcp` 将 Urban Dictionary 查找功能暴露为模型上下文协议（MCP）工具。它旨在由与 MCP 兼容的客户端启动，例如 VS Code、Claude Desktop、Codex 或自定义 Python 客户端。服务器在本地运行，通过标准输入/输出通信，并返回结构化的定义结果，AI 助手可以在聊天或代理工作流中调用。
该项目故意保持小巧：
- 无运行时 npm 依赖。
- 无数据库或后台服务。
- 无需 API 密钥。
- 使用 Node.js 内置 API。
- 在调用查找工具时，与 Urban Dictionary 的公共 JSON 端点通信。
## 工具
- `urban_dictionary_define`：查找单词或短语的定义。
- `urban_dictionary_random`：获取随机定义。
- `urban_dictionary_defid`：通过 Urban Dictionary 定义 ID 获取定义。
## 要求
- Node.js 18 或更高版本。
无需 npm 安装，因为服务器仅使用 Node.js 内置功能。
## 运行
```powershell
npm start
```
MCP 服务器通过标准输入/输出通信，因此它旨在由 MCP 客户端启动。
您也可以直接在没有 npm 的情况下运行：
```powershell
node server.js
```
直接运行后，进程等待标准输入中的 MCP JSON-RPC 消息。预计终端是安静的。
## VS Code 设置
在您的项目中创建 `.vscode/mcp.json`，或将相同的服务器条目添加到您的 VS Code 用户级 MCP 配置中：
```json
{
"servers": {
"urban-dictionary": {
"type": "stdio",
"command": "node",
"args": [
"C:\\your\\user\\file\\path\\locally"
]
}
},
"inputs": []
}
```
将 `args` 路径替换为计算机上 `server.js` 的绝对路径。
然后在 VS Code 中：
1. 打开命令面板。
2. 运行 `MCP: List Servers`。
3. 选择 `urban-dictionary`。
4. 启动或重启服务器。
5. 要求 Copilot Chat 或代理使用其中一种工具。
示例提示：
```text
使用 urban_dictionary_define 定义 "yeet"。
```
如果服务器正常工作，VS Code 应该调用本地 MCP 工具，而不是要求手动获取网页。
## Python 客户端访问
Python 应用程序可以通过将此服务器启动为标准输入/输出 MCP 服务器来访问，使用官方 MCP Python SDK。
安装 SDK：
```powershell
pip install "mcp[cli]"
```
示例 Python 客户端：
```python
import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
SERVER_PATH = r"C:\\your\\user\\file\\path\\locally"
async def main():
server_params = StdioServerParameters(
command="node",
args=[SERVER_PATH],
)
async with stdio_client(server_params) as (read, write):
async with ClientSession(read, write) as session:
await session.initialize()
tools = await session.list_tools()
print("可用工具：", [tool.name for tool in tools.tools])
result = await session.call_tool(
"urban_dictionary_define",
arguments={"term": "yeet", "limit": 1},
)
for item in result.content:
if item.type == "text":
print(item.text)
if __name__ == "__main__":
asyncio.run(main())
```
这将启动 Node.js MCP 服务器作为子进程，初始化 MCP 会话，列出可用工具，并调用 `urban_dictionary_define`。
## 通用 MCP 客户端配置
使用此检查的 `server.js` 绝对路径：
```json
{
"mcpServers": {
"urban-dictionary": {
"command": "node",
"args": [
"C:\\your\\user\\file\\path\\locally"
]
}
}
}
```
## 环境变量
- `URBAN_DICTIONARY_API_BASE`：覆盖 API 基本 URL。默认为 `https://api.urbandictionary.com/v0`。
- `URBAN_DICTIONARY_TIMEOUT_MS`：请求超时（毫秒）。默认为 `10000`。
## 测试
```powershell
npm run smoke
```
或直接运行烟雾测试：
```powershell
node scripts\smoke-test.js
```
烟雾测试使用本地伪造 Urban Dictionary API，因此无需网络访问。
## 备注
Urban Dictionary 没有发布正式的公共 API 合同。此服务器使用常用的 JSON 端点：
- `https://api.urbandictionary.com/v0/define?term=...`
- `https://api.urbandictionary.com/v0/define?defid=...`
- `https://api.urbandictionary.com/v0/random`
