警告： 这个项目是用vibe编码的，包括这个自述文件。对说明书持保留态度，不要被过于乐观的文件所愚弄。

______________________________________________________________________

JS翻译帮助代理

![Tests](TESTING.md) ![Coverage](TESTING.md) ![TypeScript](https://www.typescriptlang.org/) ![License](LICENSE) ![CloudFlare Workers](https://workers.cloudflare.com/)

用于翻译的生产就绪TypeScript MCP代理有助于为CloudFlare Workers构建多个接口。

- 接口1：核心API - 接口2:MCP HTTP服务器 - 接口3:stdio服务器 - 接口4：OpenAI API - 界面5:LLM助手

接口比较
文档
测试
部署
贡献
许可证

🎯 概述

该项目提供了一个生产就绪的统一代理服务，该服务将翻译与多个接口协议的API连接起来。所有5个接口都已完全实现和测试，测试覆盖率为98.8%。

上游服务

上游翻译有助于mcp服务 完全符合MCP标准 （从v6.6.3开始），通过标准MCP协议提供所有工具 https://translation-helps-mcp.pages.dev/api/mcp。此代理使用动态工具发现自动与上游更改保持同步。

✨ 特性

5个完整的接口 -核心API、MCP HTTP、stdio、OpenAI API、LLM助手
162测试 -98.8%通过（160/162），全面覆盖
CloudFlare工人 -无服务器部署就绪
类型安全 -带有严格模式的完整TypeScript
灵活过滤 -工具过滤、参数隐藏、注释过滤
生产就绪 -错误处理、日志记录、缓存
证据充分的 -所有接口的完整文档

🏗️ 建筑

看 ARCHITECTURE.md 详细的系统设计和组件描述。

📊 项目统计

代码行： ~5,000+
测试覆盖范围： 98.8%（160/162次测试通过）
接口： 5个完整的接口
文档： 8综合指南
示例： 多个配置示例

项目结构

src/
├── core/           # Interface 1: Core API
├── mcp-server/     # Interface 2: HTTP MCP
├── stdio-server/   # Interface 3: stdio MCP
├── openai-api/     # Interface 4: OpenAI-compatible API
├── llm-helper/     # Interface 5: OpenAI-compatible TypeScript client
└── shared/         # Shared utilities
tests/
├── unit/
├── integration/
└── e2e/
dist/
├── cjs/            # CommonJS build (for require())
└── esm/            # ESM build (for import)

入门指南

先决条件

Node.js>=20.17.0
npm或纱线

安装

npm install

配置

复制 .env.example 到 .env
填写API键和配置值

发展

# Build the project (creates both CJS and ESM builds)
npm run build

# Build only CJS
npm run build:cjs

# Build only ESM
npm run build:esm

# Run in development mode (stdio server)
npm run dev

# Run HTTP server in development mode (Wrangler)
npm run dev:http

# Run HTTP server in development mode (Native Node.js with debugging)
npm run dev:node

# Run tests
npm run test

# Lint code
npm run lint

部署

# Deploy to CloudFlare Workers
npm run deploy

用法

接口1：核心API（直接类型脚本/JavaScript）

核心API提供了对翻译帮助工具的直接编程访问。 同时支持CommonJS和ESM 为了获得最大的兼容性。

ESM（进口）：

import { TranslationHelpsClient } from 'js-translation-helps-proxy';

const client = new TranslationHelpsClient({
  enabledTools: ['fetch_scripture', 'fetch_translation_notes'],
  filterBookChapterNotes: true,
});

// Call tools using the generic callTool method
const scripture = await client.callTool('fetch_scripture', {
  reference: 'John 3:16',
});

CommonJS（必填）：

const { TranslationHelpsClient } = require('js-translation-helps-proxy');

const client = new TranslationHelpsClient({
  enabledTools: ['fetch_scripture', 'fetch_translation_notes'],
  filterBookChapterNotes: true,
});

文档： 看建筑.md 以获取完整的API参考。

______________________________________________________________________

接口2:HTTP MCP服务器

基于Web的MCP服务器，使用官方的Streamable HTTP传输，与MCP Inspector和标准MCP客户端兼容。

启动服务器：

# Development (Wrangler - CloudFlare Workers local runtime)
npm run dev:http

# Development (Native Node.js - better for debugging)
npm run dev:node

# Production (CloudFlare Workers)
npm run deploy

端点：

/mcp -官方MCP流式HTTP端点（POST+GET+DELETE）

例子：

# Initialize session
curl -X POST http://localhost:8787/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {"name": "test-client", "version": "1.0.0"}
    }
  }' -i

# List tools (use Mcp-Session-Id from initialize response)
curl -X POST http://localhost:8787/mcp \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: " \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list"
  }'

MCP检查员：

# Test with MCP Inspector
npx @modelcontextprotocol/inspector
# Connect to: http://localhost:8787/mcp

主要特点：

✅ 官方MCP流式HTTP传输
✅ 与MCP检查器兼容
✅ 客户端控制的过滤器（通过配置）
✅ 使用SSE流媒体进行会话管理
✅ CloudFlare Workers兼容

文档： MCP服务器指南

______________________________________________________________________

接口3:stdio MCP接口（按需流程）

按需流程 由MCP客户端（Claude Desktop、Cline等）启动，而不是持久服务器。

主要优势：

✅ 无后台进程 -仅在客户端需要时启动
✅ 自动生命周期 -当客户端断开连接时终止
✅ 资源效率的 -没有占用内存的空闲进程
✅ stdio传输 -通过stdin/stdout与父MCP客户端通信

与接口2和4（持久HTTP服务器）不同，这是一个 MCP客户端按需生成的进程.

快速入门：

# Run from npm (recommended)
npx js-translation-helps-proxy --help

# Or directly from GitHub:
# npx github:JEdward7777/js-translation-helps-proxy --help

# List available tools
npx js-translation-helps-proxy --list-tools

# Launch the process (for manual testing - normally the MCP client launches it)
npx js-translation-helps-proxy

注：在正常使用中，您的MCP客户端（Claude Desktop、Cline）会在需要时自动启动此过程。您不需要手动启动或管理它。

配置选项：

# Enable specific tools only
npx js-translation-helps-proxy --enabled-tools "fetch_scripture,fetch_translation_notes"

# Hide parameters from tool schemas
npx js-translation-helps-proxy --hide-params "language,organization"

# Filter book/chapter notes
npx js-translation-helps-proxy --filter-book-chapter-notes

# Set log level
npx js-translation-helps-proxy --log-level debug

MCP客户端设置：

对于Claude Desktop，请在配置文件中添加：

{
  "mcpServers": {
    "translation-helps": {
      "command": "npx",
      "args": ["js-translation-helps-proxy"]
    }
  }
}

或者使用最新的GitHub版本：

{
  "mcpServers": {
    "translation-helps": {
      "command": "npx",
      "args": ["github:JEdward7777/js-translation-helps-proxy"]
    }
  }
}

主要特点：

✅ 按需流程 -没有持续运行的服务器
✅ 客户端控制的过滤器 -按MCP客户端配置
✅ 与Claude Desktop、Cline等合作。 -任何支持stdio的MCP客户端
✅ stdio传输 -标准输入/输出通信
✅ 轻松部署npx -需要时通过npx启动客户端

文档： stdio服务器指南 | 配置示例

______________________________________________________________________

接口4:OpenAI-兼容的API

REST API OpenAI的代理 自动翻译有助于工具注入和 烘焙过滤器 （参见接口5 对于TypeScript等效）。

启动服务器：

# Development (Wrangler - CloudFlare Workers local runtime)
npm run dev:http

# Development (Native Node.js - better for debugging)
npm run dev:node

# Production (CloudFlare Workers)
npm run deploy

终点：

POST /v1/chat/completions -通过工具执行完成聊天
GET /v1/models -列出可用的OpenAI模型（代理）
GET /v1/tools -列出可用工具
GET /health -健康检查

OpenAI客户端示例：

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8787/v1",
    api_key="sk-YOUR-OPENAI-KEY"  # Your actual OpenAI API key
)

response = client.chat.completions.create(
    model="gpt-4o-mini",  # Use any OpenAI model
    messages=[
        {"role": "user", "content": "Fetch scripture for John 3:16"}
    ]
)

print(response.choices[0].message.content)

卷曲示例：

curl -X POST http://localhost:8787/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-YOUR-OPENAI-KEY" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "Fetch John 3:16"}
    ]
  }'

主要特点：

✅ OpenAI代理：使用真实的OpenAI模型和API
✅ 自动刀具注射：翻译帮助自动添加工具
✅ 烘烤过滤器: language=en, organization=unfoldingWord
✅ 迭代工具执行：处理工具调用循环
✅ 支持n>1和结构化输出
✅ CloudFlare Workers兼容

文档： OpenAI API指南

______________________________________________________________________

接口5:OpenAI兼容的TypeScript客户端

作为TypeScript类插入式替代OpenAI客户端 与Translation Helps工具自动集成。不像接口4 （HTTP/RESTneneneba API），这是一个直接的TypeScript客户端，没有网络序列化开销。 两个接口共享相同的OpenAI集成逻辑 （参见对比表). 同时支持CommonJS和ESM 为了获得最大的兼容性。

快速入门（ESM）：

import { LLMHelper } from 'js-translation-helps-proxy/llm-helper';

// Drop-in replacement for OpenAI client
const helper = new LLMHelper({
  apiKey: process.env.OPENAI_API_KEY!,
});

// Use the same API as OpenAI
const response = await helper.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [{ role: 'user', content: 'What does John 3:16 say?' }],
  n: 2  // Generate 2 completions
});

// Returns full OpenAI ChatCompletion response
console.log(response.choices[0].message.content);
console.log(response.choices[1].message.content);  // When n > 1

与OpenAI的互换性：

import { LLMHelper } from 'js-translation-helps-proxy/llm-helper';
import OpenAI from 'openai';

// Can use either client with the same code!
const client: OpenAI | LLMHelper = useTranslationHelps
  ? new LLMHelper({ apiKey })
  : new OpenAI({ apiKey });

// Same API works for both
const response = await client.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [{ role: 'user', content: 'Hello!' }]
});

快速入门（CommonJS）：

const { LLMHelper } = require('js-translation-helps-proxy/llm-helper');

const helper = new LLMHelper({
  apiKey: process.env.OPENAI_API_KEY,
});

主要特点：

✅ 插入OpenAI替换：实施 OpenAI.chat.completions.create() 接口
✅ 完全响应兼容性：返回完整的OpenAI ChatCompletion 物体
✅ 与接口4共享逻辑：相同的OpenAI SDK集成
✅ 支持所有OpenAI参数：包括 n > 1, temperature, response_format
✅ 修复 n > 1 程序错误：响应中保留所有选项
✅ 自动执行工具：翻译帮助工具自动工作
✅ 烘烤过滤器: language=en, organization=unfoldingWord
✅ 类型安全：完全支持TypeScript

文档： LLM助手指南 | 示例

______________________________________________________________________

接口比较

功能	接口1（核心）	接口2（MCP HTTP）	接口3（stdio）	接口4（OpenAI REST API）	接口5（OpenAI TypeScript客户端）
运输	直接API	HTTP	stdio	HTTP/REST	TypeScript API
后端	直接	直接	直接	OpenAI代理	OpenAI代理
网络	N/A	必填	不适用	必需	非必需
API密钥	不需要	不需要	不是必需	必需（OpenAI）	必需（OpenAI）
模型	N/A	N/A	N/A	任何OpenAI模型	任何OpenAI模型
过滤器	可配置	客户端控制	客户端控制	烤在	烤在
用例	TypeScript应用程序	Web服务	桌面应用程序	LLM集成（HTTP）	LLM整合（TypeScript）
部署	图书馆	CloudFlare工作人员	按需流程	CloudFlare工作人员	图书馆
工具执行	手动	手动	手动	自动	自动
生命周期	N/A	持久服务器	按需推出	持久服务器	不适用

选择界面2或3 当您需要客户端控制的筛选器时（请参见 MCP服务器或 stdio服务器). 选择界面3 特别是当你想要的时候 无后台进程 （按需启动）。 选择界面4或5 当你需要OpenAI与自动工具执行集成时(REST API 对比 TypeScript).

______________________________________________________________________

快速入门指南

适用于桌面应用程序（Claude Desktop、Cline）

使用 接口3 （标准版本）：

# Run from npm (recommended)
npx js-translation-helps-proxy

# Or directly from GitHub for latest development version:
# npx github:JEdward7777/js-translation-helps-proxy

用于Web服务/API

使用 接口2 （MCP-HTTP）：

# Using Wrangler (CloudFlare Workers runtime)
npm run dev:http
# Access at http://localhost:8787/mcp/*

# Using Native Node.js (better for debugging)
npm run dev:node
# Access at http://localhost:8787/mcp/*

用于LLM集成（兼容OpenAI）

使用 接口4 （OpenAI API）：

# Using Wrangler (CloudFlare Workers runtime)
npm run dev:http
# Access at http://localhost:8787/v1/*

# Using Native Node.js (better for debugging)
npm run dev:node
# Access at http://localhost:8787/v1/*

适用于Types/JavaScript项目

使用 接口1 （核心API）-同时支持ESM和CommonJS：

ESM：

import { TranslationHelpsClient } from 'js-translation-helps-proxy';

CommonJS：

const { TranslationHelpsClient } = require('js-translation-helps-proxy');

用于Types/JavaScript中的LLM集成

使用 接口5 （LLM Helper）-同时支持ESM和CommonJS：

ESM：

import { LLMHelper } from 'js-translation-helps-proxy/llm-helper';

const helper = new LLMHelper({
  apiKey: process.env.OPENAI_API_KEY!,
});

const response = await helper.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [{ role: 'user', content: 'Fetch John 3:16' }]
});

CommonJS：

const { LLMHelper } = require('js-translation-helps-proxy/llm-helper');

📚 文档

文档索引 -完整的文档中心
架构指南 -系统架构
测试指导 -测试覆盖率和策略
部署指南 -CloudFlare Workers部署
贡献指南 -如何做出贡献

接口文件

MCP HTTP服务器 -接口2文档
stdio服务器 -接口3文档
OpenAI API -接口4文档
LLM助手 -接口5文档

🧪 测试

该项目具有全面的测试覆盖范围：

# Run all tests
npm test

# Run specific test suites
npm run test:unit        # 65 unit tests
npm run test:integration # 80 integration tests
npm run test:e2e         # 8 E2E tests

测试结果：

✅ 160项测试通过（98.8%）
⏭️ 跳过2个测试（需要API密钥）

看测试.md 获取详细的测试文档。

🚀 部署

CloudFlare工人

# Build and deploy
npm run build
npm run deploy

看部署.md 获取完整的部署指南。

本地开发

# Start HTTP server (Wrangler - CloudFlare Workers runtime)
npm run dev:http

# Start HTTP server (Native Node.js - better for debugging)
npm run dev:node

# Start stdio server
npm run dev

VSCode调试

该项目包括用于调试的VSCode启动配置：

调试HTTP服务器-原生Node.js（接口2和4） -调试MCP HTTP和OpenAI API服务器
调试HTTP服务器-内置（接口2和4） -调试编译的HTTP服务器
调试stdio服务器（接口3） -调试stdio MCP服务器（使用stdin/stdout，而不是HTTP）
调试当前测试文件 -调试当前打开的测试文件

要使用：

打开要调试的文件
通过在排水沟中单击来设置断点
按 F5 或转到“运行”>“开始调试”
选择适当的调试配置

重要提示：

接口3（标准输入输出） 是一个 按需流程 由MCP客户端启动，通过stdin/stdout进行通信（不是HTTP/REST）
接口2和4 是 持久HTTP/REST服务器 可访问 http://localhost:8787
接口3具有 无后台进程 -它在需要时启动，完成后终止
服务器将以以下方式启动 LOG_LEVEL=debug 用于详细记录

🤝 贡献

我们欢迎捐款！请看贡献.md 作为指导方针。

贡献者快速入门

分叉并克隆存储库
安装依赖项： npm install
创建要素分支
通过测试进行更改
运行检查： npm run lint && npm test
提交拉取请求

📄 许可证

麻省理工学院-参见许可证文件以获取详细信息。

🙏 致谢

翻译帮助MCP -完全符合MCP标准的上游服务器（v6.6.3+）
模型上下文协议 -MCP规范
CloudFlare工人 -无服务器平台
所有贡献者 非常感谢。

📞 支持

文档： docs/INDEX.md
问题：
讨论：

______________________________________________________________________

版本： 0.2.0 | 最后更新时间： 2025-11-23 | 状态： 生产就绪✅

动态工具发现

此代理使用来自上游MCP服务器的动态工具发现。工具模式在运行时获取，确保我们始终与上游服务保持同步。上游添加/删除工具时不需要手动更新！

Js Translation Helps Proxy

快速接入

详细介绍

JS翻译帮助代理

📋 目录

🎯 概述

上游服务

✨ 特性

🏗️ 建筑

📊 项目统计

项目结构

入门指南

先决条件

安装

配置

发展

部署

用法

接口1：核心API（直接类型脚本/JavaScript）

接口2:HTTP MCP服务器

接口3:stdio MCP接口（按需流程）

接口4:OpenAI-兼容的API

接口5:OpenAI兼容的TypeScript客户端

接口比较

快速入门指南

适用于桌面应用程序（Claude Desktop、Cline）

用于Web服务/API

用于LLM集成（兼容OpenAI）

适用于Types/JavaScript项目

用于Types/JavaScript中的LLM集成

📚 文档

接口文件

🧪 测试

🚀 部署

CloudFlare工人

本地开发

VSCode调试

🤝 贡献

贡献者快速入门

📄 许可证

🙏 致谢

📞 支持

动态工具发现

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP