> 警告: 这个项目是用vibe编码的,包括这个自述文件。对说明书持保留态度,不要被过于乐观的文件所愚弄。
📋 目录
- 概述
- 特性
- 快速开始
- 接口
- 接口1:核心API
- 接口2:MCP HTTP服务器
- 接口3:stdio服务器
- 接口4:OpenAI API
- 界面5:LLM助手
- 接口比较
- 文档
- 测试
- 部署
- 贡献
- 许可证
🎯 概述
上游服务
✨ 特性
- 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或纱线
### 安装```bash
npm install
配置
- 复制
.env.example到.env - 填写API键和配置值
发展```bash
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
### 部署```bash
# Deploy to CloudFlare Workers
npm run deploy
用法
接口1:核心API(直接类型脚本/JavaScript)
ESM(进口):```typescript
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(必填):**```javascript
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客户端兼容。
启动服务器:```bash
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)
**例子:**```bash
# 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检查员:```bash
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客户端按需生成的进程**.
**快速入门:**```bash
# 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)会在需要时自动启动此过程。您不需要手动启动或管理它。
配置选项:```bash
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,请在配置文件中添加:```json
{
"mcpServers": {
"translation-helps": {
"command": "npx",
"args": ["js-translation-helps-proxy"]
}
}
}
或者使用最新的GitHub版本:```json
{
"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
**启动服务器:**```bash
# 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客户端示例:```python
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)
**卷曲示例:**```bash
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客户端
不像 接口4 (HTTP/RESTneneneba API),这是一个直接的TypeScript客户端,没有网络序列化开销。
两个接口共享相同的OpenAI集成逻辑 (参见 对比表).
同时支持CommonJS和ESM 为了获得最大的兼容性。
快速入门(ESM):```typescript
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的互换性:**```typescript
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):```javascript
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** (标准版本):```bash
# 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):```bash
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):```bash
# 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:```typescript
import { TranslationHelpsClient } from 'js-translation-helps-proxy';
**CommonJS:**```javascript
const { TranslationHelpsClient } = require('js-translation-helps-proxy');
用于Types/JavaScript中的LLM集成
使用 接口5 (LLM Helper)-同时支持ESM和CommonJS:
ESM:```typescript
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:**```javascript
const { LLMHelper } = require('js-translation-helps-proxy/llm-helper');
📚 文档
- 文档索引 -完整的文档中心
- 架构指南 -系统架构
- 测试指导 -测试覆盖率和策略
- 部署指南 -CloudFlare Workers部署
- 贡献指南 -如何做出贡献
接口文件
- MCP HTTP服务器 -接口2文档
- stdio服务器 -接口3文档
- OpenAI API -接口4文档
- LLM助手 -接口5文档
🧪 测试
该项目具有全面的测试覆盖范围:```bash
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工人```bash
# Build and deploy
npm run build
npm run deploy
看 部署.md 获取完整的部署指南。
本地开发```bash
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规范
- CloudFlare工人 -无服务器平台
- 所有贡献者 非常感谢。
📞 支持
- 文档: docs/INDEX.md
版本: 0.2.0 · 最后更新时间: 2025-11-23 · 状态: 生产就绪✅
动态工具发现
此代理使用来自上游MCP服务器的动态工具发现。工具模式在运行时获取,确保我们始终与上游服务保持同步。上游添加/删除工具时不需要手动更新!
