MCP服务器

Name: MCP服务器
Author: jentic

作者：jentic22 星标更新：2025-11-21

安装使用来源：spider==github.com

项目介绍

Jentic MCP 插件

为什么使用 Jentic MCP？

Jentic MCP 赋予开发者快速发现和集成外部 API 和工作流的能力——无需编写或维护任何特定于 API 的代码。通过利用 MCP 协议和 Jentic 的代理运行时，开发者可以：

根据功能需求搜索 API 和工作流，而不是根据供应商或实现。
立即生成与特定 API 细节无关的集成代码示例。
依靠标准化和声明性的集成来避免样板代码并减少维护。
集中精力构建功能，而 Jentic MCP 处理 API 交互的复杂性。

API 工具

Jentic MCP 插件提供了以下工具：

search_apis：在 Jentic 目录中搜索匹配特定功能需求的 API。
load_execution_info：从 Jentic 目录中检索 API 和操作的详细规范。这将包括您可能需要在 mcpServers.jentic.env 配置中提供的认证信息。
execute：执行特定的 API 或工作流操作。

快速开始

推荐的方法是从 GitHub 存储库直接使用 uvx 运行服务器。首先需要安装 uv：

brew install uv 或 pip install uv

代理 API 密钥

在 https://app.jentic.com/sign-in 创建一个代理，并复制其 API 密钥。

export JENTIC_AGENT_API_KEY=<你的代理API密钥>

按照下面的方式设置密钥在您的 MCP 客户端配置中。

配置文件的位置取决于您使用的客户端和操作系统。一些常见的例子：

Windsurf：~/.codeium/windsurf/mcp_config.json
Claude Desktop：~/Library/Application Support/Claude/claude_desktop_config.json
Claude Code：~/.claude.json
Cursor：~/cursor/.mcp.json

对于其他客户端，请查阅客户端的文档以了解如何添加 MCP 服务器。

{
    "mcpServers": {
        "jentic": {
            "command": "uvx",
            "args": [
                "--from",
                "git+https://github.com/jentic/jentic-sdks.git@main#subdirectory=mcp",
                "mcp"
            ],
            "env": {
                "JENTIC_AGENT_API_KEY": "<你的代理API密钥>"
            }
        }
    }
}

注意：保存配置文件后，您可能需要重启客户端应用程序（如 Windsurf、Claude Desktop）以便更改生效。

使用 MCP 工具

一旦 MCP 服务器运行起来，您就可以轻松地在 LLM 代理中使用 MCP 工具来发现和执行 API 和工作流。

search_apis：在 Jentic 目录中搜索匹配特定功能需求的 API。
load_execution_info：从 Jentic 目录中检索 API 和操作的详细规范。这将包括您可能需要在 mcpServers.jentic.env 配置中提供的认证信息。
execute：执行特定的 API 或工作流操作。

环境变量

当您使用需要身份验证的 API 时，load_execution_info 工具将描述所需的环境变量。您可以在 Windsurf 中通过命令行设置这些环境变量，但在某些客户端（如 Claude Desktop）中，您需要将其添加到 MCP 配置中：

{
    "mcpServers": {
        "jentic": {
            "command": "uvx",
            "args": [
                "--from",
                "git+https://github.com/jentic/jentic-sdks.git@main#subdirectory=mcp",
                "mcp"
            ],
            "env": {
                "DISCORD_BOTTOKEN=": "YOUR BOT TOKEN"
            }
        }
    }
}

替代方案（用于本地开发）：

如果您正在本地积极开发 MCP 插件，可以使用此方法。用您的项目目录的绝对路径替换 /path/to/your/project/mcp。

{
    "mcpServers": {
        "jentic": { 
            "command": "uvx",
            "args": [
                "--from",
                "/path/to/your/project/mcp",
                "mcp" 
            ]
        }
    }
}

可选：向您的 mcp_config.json 文件中添加 JENTIC_API_URL 环境变量，指向特定的 Jentic API（两种方法都适用）：

{
    "mcpServers": {
        "jentic": {
            "command": "uvx",
            "args": [
                "--from",
                "git+https://github.com/jentic/jentic-sdks.git@main#subdirectory=mcp",
                "mcp"
            ],
            "env": {
                "JENTIC_API_URL": "https://your-jentic-api.url/"
            }
        }
    }
}

配置完成后，重启 Windsurf，Jentic MCP 工具将可用。

您可以通过运行以下命令来跟踪由本地运行的 MCP 服务器生成的日志：

tail /path/to/mcp/jentic_ark2_mcp.log

安装

通过 Smithery 安装

要通过 Smithery 自动安装 Jentic 插件到 Claude Desktop：

npx -y @smithery/cli install @jentic/jentic-sdks --client claude

手动安装

确保已安装 pdm（pipx install pdm）。

为了安装开发包及其依赖项：

# 在项目根目录（例如，/Users/kc/c/sdk/mcp）
pdm install -G dev

运行 MCP 服务器

Jentic MCP 插件设计为使用 uvx 运行，它处理环境设置和执行。

默认模式（Stdio）

直接使用 uvx 运行 MCP 插件，指定项目目录作为源使用 --from 并指定 mcp 脚本：

从本地路径（开发）：

# 使用 --from 与项目目录并指定 'mcp' 脚本
uvx --from /path/to/your/project/mcp mcp

# 或者，如果从项目目录内运行：
uvx --from . mcp

从远程仓库（推荐用于一般用途）：

uvx --from \
  git+https://github.com/jentic/jentic-sdks.git@main#subdirectory=mcp \
  mcp

这会自动使用 mcp 脚本回调中定义的默认 serve --transport stdio 命令。

HTTP 模式

MCP 服务器支持两种 HTTP 传输模式：

标准 HTTP：传统的请求-响应 HTTP 模式
可流式 HTTP：具有流式支持的 HTTP 模式，兼容 MCP Inspector

标准 HTTP 模式

要在标准 HTTP 模式下运行服务器（例如，用于与 claude-cli 测试）：

从本地路径（开发）：

# 默认 HTTP（端口 8010）
uvx --from /path/to/your/project/mcp mcp serve --transport http

# 使用自定义端口
uvx --from /path/to/your/project/mcp mcp serve --transport http --port 8080

# 使用自定义主机
uvx --from /path/to/your/project/mcp mcp serve --transport http --host 0.0.0.0 --port  8080

从远程仓库（推荐）：

uvx --from \
  git+https://github.com/jentic/jentic-sdks.git@main#subdirectory=mcp \
  mcp serve --transport http --port 8080

可流式 HTTP 模式

要在可流式 HTTP 模式下运行服务器（兼容 MCP Inspector）：

从本地路径（开发）：

# 默认可流式 HTTP（端口 8010）
uvx --from /path/to/your/project/mcp mcp serve --transport streamable-http

# 使用自定义端口
uvx --from /path/to/your/project/mcp mcp serve --transport streamable-http --port 8080

# 使用自定义主机
uvx --from /path/to/your/project/mcp mcp serve --transport streamable-http --host 0.0.0.0 --port 8080

从远程仓库（推荐）：

uvx --from \
  git+https://github.com/jentic/jentic-sdks.git@main#subdirectory=mcp \
  mcp serve --transport streamable-http --port 8080

从远程 Git 仓库运行

您也可以直接从 Git 仓库 URL 运行 MCP 服务器，而无需将其克隆到本地，使用 uvx --from：

# 示例来自特定分支和子目录
uvx --from \
  git+https://github.com/jentic/jentic-sdks.git@main#subdirectory=mcp

# 解释：
# - git+https://... .git ：仓库 URL
# - @main   ：分支、标签或提交哈希
# - #subdirectory=mcp     ：包含 pyproject.toml 的仓库内的文件夹

该命令获取指定版本，在临时环境中安装其依赖项，并运行默认命令（即 serve --transport stdio）。

您可以在 URL 片段之后添加其他参数，如 --log-level DEBUG 或 --mock：

uvx --from \
  git+https://github.com/jentic/jentic-sdks.git@main#subdirectory=mcp \
  --log-level DEBUG --mock

从远程源以 HTTP 模式运行：

uvx --from \
  git+https://github.com/jentic/jentic-sdks.git@main#subdirectory=mcp \
  serve --transport http --port 8080

从远程源以可流式 HTTP 模式运行：

uvx --from \
  git+https://github.com/jentic/jentic-sdks.git@main#subdirectory=mcp \
  serve --transport streamable-http --port 8080

其他选项

日志记录

# 设置日志级别（适用于默认 stdio 或显式 serve）
uvx --from /path/to/your/project/mcp mcp --log-level DEBUG
uvx --from /path/to/your/project/mcp mcp serve --transport http --log-level DEBUG
uvx --from /path/to/your/project/mcp mcp serve --transport streamable-http --log-level DEBUG

# 将日志写入文件（适用于默认 stdio 或显式 serve）
uvx --from /path/to/your/project/mcp mcp --log-file jentic_mcp.log
uvx --from /path/to/your/project/mcp mcp serve --transport http --log-file jentic_mcp.log
uvx --from /path/to/your/project/mcp mcp serve --transport streamable-http --log-file jentic_mcp.log

模拟模式

启用模拟模式进行开发，无需连接实际的 Jentic API 知识中心：

# 模拟模式与默认 stdio
uvx --from /path/to/your/project/mcp mcp --mock

# 模拟模式与显式 HTTP
uvx --from /path/to/your/project/mcp mcp serve --transport http --mock

# 模拟模式与可流式 HTTP
uvx --from /path/to/your/project/mcp mcp serve --transport streamable-http --mock

环境变量

使用 .env 文件提供环境变量：

# 使用 .env 文件与默认 stdio
uvx --from /path/to/your/project/mcp mcp --env-file .env

# 使用 .env 文件与显式 HTTP
uvx --from /path/to/your/project/mcp mcp serve --transport http --env-file .env

# 使用 .env 文件与可流式 HTTP
uvx --from /path/to/your/project/mcp mcp serve --transport streamable-http --env-file .env

与 Claude 结合使用

MCP 插件可以与 Claude 或其他支持 MCP 规范的 LLM 结合使用：

从远程仓库运行（推荐）：

# 首先以 HTTP 模式运行服务器
uvx --from \
  git+https://github.com/jentic/jentic-sdks.git@main#subdirectory=mcp \
  mcp serve --transport http --port 8000

# 然后连接 claude-cli
claude-cli --mcp http://localhost:8000

从本地路径运行（开发）：

# 首先以 HTTP 模式运行服务器
uvx --from /path/to/your/project/mcp mcp serve --transport http --port 8000

# 然后连接 claude-cli
claude-cli --mcp http://localhost:8000

开发

参见 CLAUDE.md 获取详细的开发指南。

包结构

src/mcp/：主要的 MCP 包
- mock/：开发用的模拟数据提供者
- tools.py：工具定义
- handlers.py：请求处理器
- main.py：CLI 入口点
- adapters/：适配器实现
- core/：核心功能
tests/：测试套件

测试

# 确保已安装开发依赖项：pdm install -G dev
pdm run test

代码检查与格式化

使用 ruff、black、isort、mypy 通过 pdm 脚本。

# 运行所有检查和格式化工具
pdm run lint

# 仅运行 ruff
pdm run linter