Mammoth Analytics

mammoth-mcp-server

Mammoth MCP 服务。AI 客户端（Claude、ChatGPT）使用其工具，以当前登录用户的身份在 Mammoth 中探索、清理、转换和导出数据。

该服务依赖一个 Mammoth 软件包：SDK（mammoth-io）。每个工具都像 SDK 一样通过 API 访问 Mammoth。该服务不会导入任何后端代码。

托管或本地运行

• 托管： Mammoth 在 https://mcp.mammoth.io/mcp 运行此服务。将该 URL 添加到你的 MCP 客户端，并使用 Mammoth 账户登录（OAuth）。无需安装。
• 本地： 运行 pip install mammoth-mcp-server，然后设置 MCP_ENCRYPTION_KEY 并启动 mammoth-mcp-server（请参阅下文的 在虚拟环境中运行）。MCP_ENCRYPTION_KEY 必须是 Fernet 密钥：由 32 个经过 URL 安全编码的 base64 字节组成。使用 python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())" 生成。未设置该密钥，或设置的值不是 Fernet 密钥时，服务将拒绝启动。

目录结构

路径	内容
mammoth_mcp_server/tools/	各类工具，每个领域对应一个模块（视图、流水线、文件、仪表板等）。
mammoth_mcp_server/sdk.py	工具调用所使用的 SDK 客户端，以及以模型可用的文字描述的 API 错误。
mammoth_mcp_server/jobs.py	等待 API 路由启动的任务完成。
mammoth_mcp_server/task_params.py	将转换映射到 API 所需流水线任务的映射表。
mammoth_mcp_server/tokens.py	检查调用方的令牌：Mammoth 会说明令牌是否有效，以及对应哪个服务。
mammoth_mcp_server/store.py	Redis 中的短期记录：上传票据。
mammoth_mcp_server/upload_routes.py	用户拖放本地文件的页面。
mammoth_mcp_server/server_card.py	位于 /.well-known/mcp/server-card.json 的公开服务卡片。
mammoth_mcp_server/shape.py	从 API 响应中提取并交给模型的读取工具数据。
mammoth_mcp_server/app.py	ASGI 应用和 main()。
mammoth_mcp_server/config.py	所有部署设置，均从环境中读取。

设置

变量	默认值	含义
MCP_SERVER_URL	https://mcp.mammoth.io	客户端访问此服务时使用的地址。
MAMMOTH_APP_URL	https://app.mammoth.io	Web 应用地址，供工具提供给用户的链接使用。
MAMMOTH_DASHBOARD_URL	MAMMOTH_APP_URL	提供已发布仪表板的主机。
MAMMOTH_API_URL	MAMMOTH_APP_URL + /api/v2	每次工具调用所访问的 API。
MAMMOTH_API_ROOT	/api/v2	API 所在路径。若直接访问 API，请将其设为空。
MAMMOTH_OAUTH_URL	MAMMOTH_APP_URL + /api/v2	Mammoth 的授权服务（发行方），客户端在此处为用户登录。
MCP_REDIS_URL	redis://localhost:6379/0	上传票据的存储位置。
MCP_ENCRYPTION_KEY	无	Fernet 密钥。上传票据中的调用方令牌使用该密钥加密。必填。
MCP_STORE_PREFIX	mammoth_mcp	在共享 Redis 中区分此部署的记录。
MCP_HOST、MCP_PORT	127.0.0.1、8270	服务的监听地址。

登录

此服务不会为任何人办理登录。登录由 Mammoth 自己的授权服务器负责，也就是 Mammoth API 提供的 OAuth 服务。此服务仅是 OAuth 资源服务器。

1. 客户端在没有令牌的情况下调用 /mcp。服务返回 401，并指向 /.well-known/oauth-protected-resource/mcp。
2. 该文档会指定 Mammoth 的授权服务器（MAMMOTH_OAUTH_URL）。客户端读取该服务器的 元数据，并将用户转到该服务器。
3. 用户登录 Mammoth，选择工作区和项目，然后批准授权。客户端为此服务的 URI <MCP_SERVER_URL>/mcp 请求令牌（resource 参数，RFC 8707）。
4. 客户端使用该令牌调用 /mcp。每次请求时，服务都会向 Mammoth 查询令牌的用途 （GET /workspaces/current）。只有 Mammoth 确认令牌有效，且签发给此服务的 URI 时，服务才会接受该令牌。
5. 每次工具调用都会使用同一个令牌发送到 Mammoth API，因此会应用用户的权限。

令牌属于一个工作区。针对其他工作区的工具调用会被拒绝。在工作区设置中手动创建的 Mammoth API 令牌没有签发给任何服务，因此此服务会拒绝它。

此服务不会保存登录状态或令牌，只有一个例外：上传链接会将调用者的令牌加密后保存在 Redis 中，直到用户上传文件或 30 分钟过去。

Mammoth 需要配置的内容

• 在 mvc-service 的 const.ini 文件 [oauth] 部分中，将 MCP 服务的 URI <MCP_SERVER_URL>/mcp 配置到 MCP_RESOURCES。Mammoth 不会为其他资源签发令牌。
• GET /workspaces/current 必须在工作区 id 旁返回令牌的 resource。否则此服务会拒绝所有令牌。

下文的在环境中正常运行前列出了需要检查的每个步骤及其顺序。

运行

作为容器运行，只需在主机上安装 Docker

镜像基于此仓库构建，因此部署不必等待 SDK 发布。请从仓库根目录（即构建上下文）构建：

cp mammoth-mcp-server/deploy/.dockerignore.example .dockerignore
docker build -f mammoth-mcp-server/deploy/Dockerfile -t mammoth-mcp-server .
docker run --env-file mammoth-mcp-server/deploy/.env -p 8270:8270 mammoth-mcp-server

使用独立的 Redis，作为一个栈运行：

cp mammoth-mcp-server/.env.example mammoth-mcp-server/deploy/.env   # then set the values
docker compose -f mammoth-mcp-server/deploy/compose.yaml up -d --build

服务不会在请求之间将内容保存在内存中，因此可以通过增加容器来扩展。容器之间只共享 Redis。

从虚拟环境运行

pip install mammoth-mcp-server
cp .env.example .env        # then set the values
mammoth-mcp-server          # or: uvicorn mammoth_mcp_server.app:create_app --factory

deploy/ 中的内容

文件	用途
Dockerfile	基于此仓库构建的镜像
compose.yaml	将服务和 Redis 作为一个栈运行
.dockerignore.example	构建前复制到仓库根目录
mammoth-mcp-server-container.service.example	使用 systemd 运行容器
mammoth-mcp-server.service.example	使用 systemd 运行虚拟环境
nginx.example.conf	部署所需的两个服务器块

在环境中正常运行前

以下每一项单独出现都会导致登录失败，因此请按顺序检查。

1. DNS 和入口将 MCP_SERVER_URL 指向服务端口。 deploy/nginx.example.conf 中包含服务器块。

2. 已设置 MCP_ENCRYPTION_KEY。这是此服务唯一保存的密钥。 没有其他必需且无默认值的配置项；请参见设置。

3. **Mammoth 已配置此服务：**在 mvc-service 的 const.ini 文件 [oauth] 部分中设置 MCP_RESOURCES = <MCP_SERVER_URL>/mcp。Mammoth 不会为其他资源签发令牌。

4. Mammoth 主机在客户端查找的位置提供其 OAuth 元数据。 对于带路径的颁发者，RFC 8414 要求将文档放在 /.well-known/oauth-authorization-server/api/v2，而 apiv2 在其自身路径提供该文档，因此入口必须将两者拼接起来。deploy/nginx.example.conf 中的第二个服务器块实现了这一点。使用以下命令检查：

   curl https://<mammoth host>/.well-known/oauth-authorization-server/api/v2
   

   必须返回该文档，而不是 404。

5. **Web 应用的 OAuth 授权页面已部署。**否则用户会进入一个不存在的页面，也无法批准授权。

完成后，客户端连接到 <MCP_SERVER_URL>/mcp，用户登录 Mammoth，并选择工作区和项目。

测试

cd mammoth-mcp-server
python -m pytest tests -q

测试不会连接任何服务。SDK 客户端和工具都是真实的；只有客户端下方的 HTTP 传输层被替换了。