Ntealan Apis Mcp Server

---

🦜 目录

• 功能
• 快速开始
  • 前提条件
  • 安装
  • 运行服务
• 项目结构
• 用法
  • 资源
  • 工具
• 贡献
• 联系

---

🦜 功能

• 词典管理：创建、更新、删除和检索词典及其元数据。
• 词条管理：管理词典中的词条，包括统计信息和筛选。
• 贡献管理：跟踪和管理用户对词条和词典的贡献。
• 可扩展的 MCP 服务：轻松添加新的资源和工具。
• 异步支持：基于 fastmcp 和 aiohttp 构建，性能出色。
• 类似 OpenAPI 的资源注册：使用 URI 和标签注册资源和工具。

---

🦜 快速开始

前提条件

• Python 3.11+
• uv
• aiohttp
• pydantic
• fastmcp（或其分支）
• aiodns
• python-dotenv

安装

通过 pip 安装

克隆仓库并安装依赖项：

git clone https://github.com/Levis0045/ntealan-apis-mcp-server.git
cd ntealan-apis-mcp-server
pip install .

（可选）安装并使用 uv 以更快地管理依赖项

如果你希望更快地安装依赖项并使用现代 Python 打包方式，可以在 ntealan-apis-mcp-server 目录中使用 uv：

uv sync

运行服务

启动 MCP 服务：

python -m ntealanmcp -t stdio

或者，如果你已安装 uv，可以运行服务命令：

ntealanmcp -t stdio

服务默认使用 Server-Sent Events (sse) 传输方式，并在此端点运行：http://127.0.0.1:8000/sse。如有需要，可以在 main.py 中修改传输方式。

---

🦜 项目结构

ntealan-api/
├── src/
│   └── ntealan_apis_mcp/
│       ├── main.py
│       ├── models/
│       │   ├── article.py
│       │   ├── contribution.py
│       │   ├── dictionary.py
│       │   └── common.py
│       ├── primitives/
│       |    ├── resources/
│       │    │   ├── article.py
│       │    │   ├── contribution.py
│       │    │   └── dictionary.py
│       |    └── tools/
│       |        ├── article.py
│       |        ├── contribution.py
│       |        └── dictionary.py
│       └── common/
│           ├── utils.py
│           ├── cache.py
│           └── http_session.py
├── examples/
├── tests/
├── pyproject.toml
└── requirements.txt

---

🦜 用法

基础资源

资源是异步函数，用于从 NTeALan API 端点公开字典、文章和贡献的数据。它们会注册到 MCP 服务中，并可通过自定义 URI 调用。

资源注册示例：

ntl_mcp_server.add_resource_fn(
    lambda dictionary_id, article_id, params: get_article_by_id(
        dictionary_id, article_id, params, ntl_mcp_server.get_context()
    ),
    name="get_article_by_id",
    uri="ntealan-apis://articles/dictionary/{dictionary_id}/{article_id}?{params}",
    tags=["article-endpoint", "mcp-resource"],
    mime_type="application/json",
    description="Get an article by ID"
)

# or just use the classic integration
@ntl_mcp_server.resource(
    uri="ntealan-apis://articles/dictionary/{dictionary_id}/{article_id}?{params}",
    tags=["article-endpoint", "mcp-resource"],
    mime_type="application/json"
)
async def get_article_by_id(
    dictionary_id: str, article_id: UUID,
    params: str, ctx: Context
) -> McpResourceResponse:
    """
    Retrieve a article by its unique identifier.
    """
    # Placeholder logic
    return {"status": "OK", "data": f"Hello, {article_id}!"}

现有资源及其状态列表：

名称 / URI 模式	描述	参数	开发状态
ntealan-apis://dictionaries/dictionary/{dictionary_id}	按 ID 获取字典元数据	dictionary_id	稳定
ntealan-apis://dictionaries?limit=2	获取所有字典元数据	limit	稳定
ntealan-apis://dictionaries/statistics/{dictionary_id}	获取特定字典的统计信息	dictionary_id	稳定
ntealan-apis://dictionaries/statistics	获取所有字典的统计信息	无	稳定
ntealan-apis://articles/dictionary/{dictionary_id}/{article_id}?none	按 ID 获取文章	dictionary_id、article_id	稳定
ntealan-apis://articles?limit=2	获取所有文章	limit	稳定
ntealan-apis://articles/dictionary/{dictionary_id}?limit=2	获取某个字典的所有文章	dictionary_id、limit	稳定
ntealan-apis://articles/statistics/{dictionary_id}	获取某个字典的文章统计信息	dictionary_id	稳定
ntealan-apis://articles/statistics	获取所有文章的统计信息	无	不稳定
ntealan-apis://contributions/{dictionary_id}/{contribution_id}	按 ID 获取贡献	dictionary_id、contribution_id	稳定
ntealan-apis://greeting/Elvis	问候资源	name	稳定
ntealan-apis://articles/dictionaries/search/{dictionary_id}?q=mba&page=1&limit=1	在字典中搜索文章	dictionary_id、q、page、limit	稳定
ntealan-apis://articles/search?q=mba&page=1	搜索文章	q、page	稳定
ntealan-apis://dictionaries/search?q=yemb&page=1&limit=1	搜索字典	q、page、limit	稳定

基础工具

工具是用于创建、更新和删除词典、文章和贡献的实用函数。

工具注册示例：

ntl_mcp_server.add_tool(
    create_dictionary,
    description="Create a new dictionary",
    tags=["mcp-tool", "dictionary-endpoint"]
)

现有工具列表及状态（尚未实现）：

工具名称	描述	必需的载荷字段	开发状态
create_dictionary	创建新词典	data（词典字段）	尚未开始
update_dictionary	更新现有词典	dictionary_id、data（要更新的字段）	尚未开始
delete_dictionary	删除词典	dictionary_id	尚未开始
create_article	创建新文章	dictionary_id、data（文章字段）	尚未开始
update_article	更新文章	dictionary_id、article_id、data（要更新的字段）	尚未开始
delete_article	删除文章	dictionary_id、article_id	尚未开始
create_contribution	创建新贡献	dictionary_id、article_id、data（贡献字段）	尚未开始
update_contribution	更新贡献	dictionary_id、article_id、contribution_id、data	尚未开始
delete_contribution	删除贡献	dictionary_id、article_id、contribution_id	尚未开始

运行示例

查看 examples/ 文件夹以运行和测试一些示例。

# for all resources
uv run examples/run_client_resources.py -t sse -e prod -s 8
# for all tools
uv run examples/run_client_tools.py -t stdio -e local -s 0

你可以在以下位置获取文档：

# for all resources
uv run examples/run_client_resources.py -h
# for all tools
uv run examples/run_client_tools.py -h

使用 Docker 部署

你可以使用 Docker 部署 MCP 服务，并在生产环境中通过 Nginx 反向代理提供服务。

1. 构建 Docker 镜像

手动构建 Docker 镜像：

docker build -t ntealan-mcp-server .

2. 或自动构建并启动服务

• 获取并检查最新版本的 compose 和 Docker。响应中会显示 Docker Compose version v2.35.1。

docker compose version

• 构建并启动服务

docker compose up --build -d

• 现在可以通过此地址 http://0.0.0.0:8000 或你配置的域名访问 MCP 服务。

• 使用 MCP 客户端连接到 http://127.0.0.1:8000/sse 或你配置的域名。

使用 Smithery 连接

• 安装 mcp cli

uv add "mcp[cli]"

• 使用 MCP 客户端连接

import mcp
from mcp.client.websocket import websocket_client
import json
import base64

smithery_api_key = "your-api-key"
url = f"wss://server.smithery.ai/@Levis0045/ntealan-apis-mcp-server/ws?api_key={smithery_api_key}"

async def main():
    # Connect to the server using websocket client
    async with websocket_client(url) as streams:
        async with mcp.ClientSession(*streams) as session:
            # Initialize the connection
            await session.initialize()
            # List available tools
            tools_result = await session.list_tools()
            print(f"Available tools: {', '.join([t.name for t in tools_result.tools])}")

            # Example of calling a tool:
            # result = await session.call_tool("tool-name", arguments={"arg1": "value"})

if __name__ == "__main__":
    import asyncio
    asyncio.run(main())

---

🦜 贡献

请在此文件中了解更多信息：CONTRIBUTION.md

🦜 联系方式

• 项目负责人：Elvis Mboning@NTeALan
• NTeALan API 文档：https://apis.ntealan.net/ntealan
• GitHub Issues：https://github.com/Levis0045/ntealan-apis-mcp-server/issues
• 电子邮件：[email protected]