Alfanous MCP 服务器

关键词

quranarabic-nlptranslationai-assistantjson-rpc

使用说明（简要可操作的步骤，适用于开发者与运维人员）

  • 项目简介

    • 该仓库实现了一个完整的 MCP 服务器，能够通过 MCP 协议接收请求、调用 Alfanous 的后端 API 进行 Quranic 内容检索、翻译及元数据获取，并将结果以 JSON-RPC 的格式返回给 MCP 客户端。
    • 服务器核心功能包括：托管资源与数据、注册并执行工具（Tools，如 search_quran、search_translations、get_quran_info 等）、定义/渲染 Prompt 模板，以及提供对外统一的接口以供 LLM 客户端在对话中获取上下文信息与能力。

  • 主要功能点

    • MCP 服务器核心实现：基于 FastMCP 框架搭建，提供标准的 MCP 请求/响应处理能力。
    • 资源与工具暴露：实现多种工具函数，如检索 Quran verses、翻译文本、主题/统计检索、按位置检索、按语言处理的词汇信息，以及获取词汇字段值等。
    • 与后端 API 交互：通过 alfanous.api 提供的接口对接实际后端逻辑，统一以 MCP 工具的格式响应。
    • 安全与可扩展性：服务器设计支持会话管理、能力声明，以及未来通过多传输协议进行通信的能力扩展（示例支持 stdio，理论上可扩展为流式/WebSocket 等形式）。

  • 安装与运行

    • 安装 MCP 服务器依赖包（示例名称：alfanous3-mcp）。
    • 在命令行直接启动服务器：
      • 运行方式示例：python -m alfanous_mcp.mcp_server
    • 启动后，服务器将以 stdio 方式对外提供 MCP 服务，且可通过配置文件/客户端进行连接。

  • 服务器配置（供 MCP 客户端使用的配置示例，JSON 文件描述，非代码片段） 注意：以下信息仅用于 MCP 客户端完成连接与调用配置，不属于代码实现的一部分，客户端无需打包到服务器端。请按以下 JSON 结构在客户端配置中填写对应字段： { "server_name": "alfanous", "transport": "stdio", "command": "python", "args": ["-m", "alfanous_mcp.mcp_server"], "tools": [ "search_quran", "search_translations", "get_quran_info", "search_quran_by_themes", "search_quran_by_stats", "search_quran_by_position", "search_by_word_linguistics", "list_field_values", "suggest_query", "correct_query", "get_ai_rules", "get_word_children_schema" ], "notes": "以上工具名称与实现请以服务器实际暴露的工具集合为准，若新增/变更，请同步更新客户端配置。" }

  • 基本使用方法

    • 服务器启动后，MCP 客户端（如 Claude Desktop、Copilot 等）可以通过配置的 MCP 服务器进行交互。
    • 客户端调用的核心能力包括：资源访问、工具调用、提示/模板获取等，后端统一返回 JSON-RPC 风格的响应。
    • 若你是开发者，建议：
      • 通过单元测试覆盖 MCP 工具的输入输出，确保 JSON-RPC 请求与响应符合协议预期。
      • 在生产环境中使用日志与错误处理，以便追踪工具调用链和能力声明。
    • 参考测试覆盖面：仓库中的测试用例已覆盖了多种 MCP 工具（如 search_quran、search_translations、get_quran_info、suggest_query、correct_query、list_field_values 等），可据此编写/验证集成用例。

  • 重要注意事项

    • MCP 服务端的实现细节以本仓库代码为准，确保与客户端的 JSON-RPC 调用参数、字段名和返回结构保持兼容。
    • 出于安全与稳定性考虑，生产环境建议对 MCP 请求进行鉴权与速率限制，并对返回结果做适当的错误封装与日志记录。

服务器信息

访问项目