Jentic

Jentic MCP 插件

为什么使用 Jentic MCP？

Jentic MCP 让开发者能够快速发现并集成外部 API 和工作流——无需编写或维护任何特定于 API 的代码。借助 MCP 协议和 Jentic 的 agentic 运行时，开发者可以：

• 按能力而非供应商或实现来搜索 API 和工作流。
• 即时生成与具体 API 细节无关的集成代码示例。
• 依靠标准化、声明式的集成，避免样板代码并减少维护工作。
• 专注于构建功能，由 Jentic MCP 处理 API 交互的复杂性。

API 工具

Jentic MCP 插件提供以下工具：

1. search_apis：在 Jentic 目录中搜索符合特定功能需求的 API
2. load_execution_info：从 Jentic 目录中检索 API 和操作的详细规范。其中会包含你可能需要在 mcpServers.jentic.env 配置中提供的认证信息。
3. execute：执行特定的 API 或工作流操作。

快速开始

推荐的方法是使用 uvx 直接从 GitHub 仓库运行该服务。 你需要先安装 uv，使用以下命令：

brew install uv 或 pip install uv

Agent API 密钥

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

export JENTIC_AGENT_API_KEY=<your-agent-api-key>

按下文所示，在你的 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": "<your-agent-api-key>"
            }
        }
    }
}

注意： 保存配置文件后，你可能需要重启客户端应用（Windsurf、Claude Desktop）才能使更改生效。

MCP 工具使用

MCP 服务运行后，你就可以轻松地在你的大模型 Agent 中使用 MCP 工具来发现和执行 API 与工作流。

1. search_apis：在 Jentic 目录中搜索符合特定功能需求的 API
2. load_execution_info：从 Jentic 目录中检索 API 和操作的详细规范。其中会包含你可能需要在 mcpServers.jentic.env 配置中提供的认证信息。
3. 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 自动为 Claude Desktop 安装 Jentic 插件：

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

手动安装

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

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

# From the project root directory (e.g., /Users/kc/c/sdk/mcp)
pdm install -G dev

运行 MCP 服务

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

默认模式（Stdio）

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

从本地路径（开发）：

# Use --from with the project directory and specify the 'mcp' script
uvx --from /path/to/your/project/mcp mcp

# Or, if running from within the project directory:
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 测试）：

从本地路径（开发）：

# Default HTTP (port 8010)
uvx --from /path/to/your/project/mcp mcp serve --transport http

# With custom port
uvx --from /path/to/your/project/mcp mcp serve --transport http --port 8080

# With custom host
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）：

从本地路径（开发）：

# Default streamable HTTP (port 8010)
uvx --from /path/to/your/project/mcp mcp serve --transport streamable-http

# With custom port
uvx --from /path/to/your/project/mcp mcp serve --transport streamable-http --port 8080

# With custom host
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：

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

# Explanation:
# - git+https://... .git : The repository URL
# - @main   : The branch, tag, or commit hash
# - #subdirectory=mcp     : The folder within the repo containing the 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

其他选项

日志

# Set logging level (applies to default stdio or explicit 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

# Log to file (applies to default stdio or explicit 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

Mock 模式

启用 mock 模式以便在未连接到实际 Jentic API Knowledge Hub 的情况下进行开发：

# Mock mode with default stdio
uvx --from /path/to/your/project/mcp mcp --mock

# Mock mode with explicit HTTP
uvx --from /path/to/your/project/mcp mcp serve --transport http --mock

# Mock mode with streamable HTTP
uvx --from /path/to/your/project/mcp mcp serve --transport streamable-http --mock

环境变量

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

# Env file with default stdio
uvx --from /path/to/your/project/mcp mcp --env-file .env

# Env file with explicit HTTP
uvx --from /path/to/your/project/mcp mcp serve --transport http --env-file .env

# Env file with streamable HTTP
uvx --from /path/to/your/project/mcp mcp serve --transport streamable-http --env-file .env

与 Claude 配合使用

该 MCP 插件可与 Claude 或其他支持 MCP 规范的大模型配合使用：

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

# Run the server in HTTP mode first
uvx --from \
  git+https://github.com/jentic/jentic-sdks.git@main#subdirectory=mcp \
  mcp serve --transport http --port 8000

# Then connect claude-cli
claude-cli --mcp http://localhost:8000

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

# Run the server in HTTP mode first
uvx --from /path/to/your/project/mcp mcp serve --transport http --port 8000

# Then connect claude-cli
claude-cli --mcp http://localhost:8000

开发

有关详细的开发说明，请参阅 CLAUDE.md。

包结构

• src/mcp/：主 MCP 包
  • mock/：用于开发的 Mock 数据提供程序
  • tools.py：工具定义
  • handlers.py：请求处理器
  • main.py：命令行入口点
  • adapters/：适配器实现
  • core/：核心功能
• tests/：测试套件

测试

# Ensure dev dependencies are installed: pdm install -G dev
pdm run test

代码检查与格式化

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

# Run all linters/formatters
pdm run lint

# Run only ruff
pdm run linter