Quotes Server Claude Code

MCP报价服务器

](https://www.npmjs.com/package/@rhofkens/mcp-quotes-server-claude-code) ](https://www.npmjs.com/package/@rhofkens/mcp-quotes-server-claude-code)  

](https://nodejs.org)    

一个模型上下文协议（MCP）服务器，它提供了一个简单的工具，用于使用Serper.dev API搜索名人和非名人的报价。

特性

• 报价搜索：两种报价检索工具-标准版和弹性版
• 主题筛选：可选择按特定主题过滤引号
• 灵活的结果：每次搜索请求1-10个报价
• 弹性模式：缓存、断路器、重试逻辑和回退机制
• 提示模板：针对不同用例的多个结构化模板
• 增强的错误消息：具有明确恢复步骤的可操作错误消息
• 性能优化：预热缓存，请求重复数据删除
• 运输选项：STDIO和HTTP传输模式
• 健康监测：内置健康检查和绩效指标
• TypeScript支持：出口型号的全型安全
• MCP协议：完全符合MCP标准，可与Claude和其他AI助手一起使用

安装

全局安装（推荐）

npm install -g @rhofkens/mcp-quotes-server-claude-code

或者直接与npx一起使用

npx @rhofkens/mcp-quotes-server-claude-code

快速开始

# Install globally
npm install -g @rhofkens/mcp-quotes-server-claude-code

# Set your Serper.dev API key
export SERPER_API_KEY="your-serper-api-key"

# Run the server
mcp-quotes-server-claude-code

用法

运行服务器

全局安装后：

# Set your Serper.dev API key
export SERPER_API_KEY="your-serper-api-key"

# Run the server
mcp-quotes-server-claude-code

或者直接运行而无需安装：

# Set your Serper.dev API key
export SERPER_API_KEY="your-serper-api-key"

# Run with npx
npx @rhofkens/mcp-quotes-server-claude-code

MCP检验员测试

# Test the server using MCP Inspector
npx @modelcontextprotocol/inspector npx @rhofkens/mcp-quotes-server-claude-code

与Claude Desktop一起使用

将服务器添加到您的Claude Desktop配置中：

对于全局安装：

{
  "mcpServers": {
    "quotes": {
      "command": "mcp-quotes-server-claude-code",
      "env": {
        "SERPER_API_KEY": "your-serper-api-key"
      }
    }
  }
}

或者使用npx：

{
  "mcpServers": {
    "quotes": {
      "command": "npx",
      "args": ["@rhofkens/mcp-quotes-server-claude-code"],
      "env": {
        "SERPER_API_KEY": "your-serper-api-key"
      }
    }
  }
}

使用HTTP传输

服务器支持STDIO（默认）和HTTP传输模式。要使用HTTP传输，请执行以下操作：

# Start the server with HTTP transport
export MCP_TRANSPORT=http
export MCP_HTTP_PORT=3000
export MCP_HTTP_HOST=localhost
export MCP_HTTP_PATH=/mcp
export SERPER_API_KEY="your-serper-api-key"

mcp-quotes-server-claude-code

服务器将于启动 http://localhost:3000/mcp 并接受遵循MCP流式HTTP传输规范的POST请求（2025-03-26）。

HTTP传输配置

• MCP_TRANSPORT：设置为 http 启用HTTP传输（默认值： stdio)
• MCP_HTTP_PORT：HTTP服务器的端口（默认值： 3000)
• MCP_HTTP_HOST：HTTP服务器的主机（默认值： localhost)
• MCP_HTTP_PATH：MCP端点的路径（默认值： /mcp)

HTTP请求示例

初始化会话：

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

调用getQuotes工具：

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id": "your-session-id" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "getQuotes",
      "arguments": {
        "person": "Albert Einstein",
        "numberOfQuotes": 3,
        "topic": "science"
      }
    }
  }'

健康检查：

curl http://localhost:3000/health
# Returns: {"status":"ok","transport":"http","sessions":0}

API

工具

getQuotes

搜索特定人的语录。

参数：

• person （string，必填）：要查找其引号的人的姓名
• numberOfQuotes （number，必填）：要返回的引号数量（1-10）
• topic （字符串，可选）：用于筛选引号的特定主题

例子：

{
  "person": "Albert Einstein",
  "numberOfQuotes": 3,
  "topic": "science"
}

getResilientQuotes

通过缓存、断路器和自动回退等弹性模式增强报价检索。

参数：

• person （string，必填）：要查找其引号的人的姓名
• numberOfQuotes （number，必填）：要返回的引号数量（1-10）
• topic （字符串，可选）：用于筛选引号的特定主题

特征：

• 1小时TTL自动缓存
• 断路器保护
• 具有指数回退的自动重试
• 服务不可用时回退到缓存数据
• 返回有关缓存状态的元数据

例子：

{
  "person": "Maya Angelou",
  "numberOfQuotes": 3,
  "topic": "courage"
}

响应包括元数据：

{
  "quotes": [
    {
      "text": "I've learned that people will forget what you said...",
      "author": "Maya Angelou",
      "source": "https://example.com/angelou-quotes"
    }
  ],
  "metadata": {
    "cacheHit": true,
    "fallbackUsed": false,
    "retryCount": 0,
    "searchQueries": ["Maya Angelou courage quotes"]
  }
}

资源

报价提示模板

针对不同报价相关用例的多个结构化模板。

可用模板：

• quote-prompt://default -通用标准模板
• quote-prompt://research -以引文为重点的学术研究模板
• quote-prompt://creative -创意写作和灵感模板
• quote-prompt://list -列出所有可用模板

示例URI： quote-prompt://default

文档

• 综合使用示例 -详细的示例和集成模式
• API文档 -完整的API参考
• 测试指导 -测试策略和示例
• 部署指导 -生产部署说明
• 性能指南 -性能基准和优化
• 手动测试检查表 -预发布验证检查表

发展

设置

# Clone the repository
git clone https://github.com/rhofkens/mcp-quotes-server-claude-code.git
cd mcp-quotes-server-claude-code

# Install dependencies
npm install

# Set up environment
cp .env.example .env
# Edit .env and add your SERPER_API_KEY

# Build the project
npm run build

脚本

• npm run build -构建TypeScript项目
• npm run dev -以热重载的开发模式运行
• npm test -运行单元测试
• npm run test:unit -仅运行单元测试
• npm run test:integration -运行集成测试
• npm run test:coverage -使用覆盖率报告运行测试
• npm run test:watch -在监视模式下运行测试
• npm run typecheck -运行TypeScript类型检查
• npm run lint -运行ESLint
• npm run lint:fix -运行ESLint并自动修复
• npm run format -使用Prettier格式化代码
• npm run format:check -检查代码格式
• npm run clean -清理构建工件
• npm run precommit -运行预提交检查

测试

# Run all tests
npm test

# Run unit tests only
npm run test:unit

# Run integration tests
npm run test:integration

# Run tests with coverage
npm run test:coverage

# Test the server manually
npm run dev
# In another terminal:
npx @modelcontextprotocol/inspector npx @rhofkens/mcp-quotes-server-claude-code

配置

服务器需要以下环境变量：

• SERPER_API_KEY （必需）：用于搜索报价的Serper.dev API密钥

可选配置：

• NODE_ENV：设置为“生产”以进行生产部署
• LOG_LEVEL：设置日志记录级别（调试、信息、警告、错误）
• MCP_TRANSPORT：传输类型-“stdio”（默认）或“http”
• MCP_HTTP_PORT：使用HTTP传输时的HTTP服务器端口（默认值：3000）
• MCP_HTTP_HOST：使用HTTP传输时的HTTP服务器主机（默认值：localhost）
• MCP_HTTP_PATH：使用HTTP传输时的HTTP端点路径（默认值：/mcp）

建筑

服务器由以下组件构建：

• TypeScript用于类型安全
• 用于协议实现的MCP SDK
• Axios用于向Serper.dev发送HTTP请求
• Zod用于输入验证
• Jest用于单元测试
• 用于HTTP传输模式的Express.js

高级功能

弹性模式

getResilientQuotes工具实现了几种弹性模式：

1. 缓存层

- 具有1小时TTL的内存缓存 - 自动缓存失效 - 重新验证模式时失效 - 用于热门查询的预热缓存

1. 断路器

- 防止级联故障 - 自动恢复测试 - 可配置阈值 - 健康状态监测

1. 重试逻辑

- 指数退避 - 最多3次重试尝试 - 智能错误检测

1. 回退机制

- 过时的缓存回退 - 部分结果处理 - 优雅降级

1. 速率限制

- 请求重复数据删除 - API配额管理 - 突发保护

故障排除

常见问题

找不到SERPER_API_KEY

Error: Configuration error: Missing or invalid SERPER_API_KEY

解决方案：

# Set the API key in your environment
export SERPER_API_KEY="your-api-key-here"

# Or add to .env file
echo "SERPER_API_KEY=your-api-key-here" >> .env

认证失败

Error: Authentication failed for serper

解决方案：

1. 验证您的API密钥是否正确
2. 检查钥匙是否处于活动状态https://serper.dev/dashboard
3. 确保您没有超出计划限制

超出费率限制

Error: Rate limit exceeded for serper

解决方案：

1. 请等待几分钟，然后重试
2. 减少numberOfQuotes参数
3. 随着时间的推移，将您的请求间隔开
4. 考虑升级您的Serper.dev计划

未找到报价

如果服务器返回空引号数组：

1. 检查此人的姓名拼写
2. 先尝试不使用主题过滤器
3. 使用更常见的名称变体
4. 确保该人为公众所知

调试模式

启用调试日志记录以进行详细的故障排除：

export LOG_LEVEL=debug
export NODE_ENV=development
mcp-quotes-server-claude-code  # If installed globally
# OR
npx @rhofkens/mcp-quotes-server-claude-code  # If using npx

贡献

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。

致谢

• 使用 模型上下文协议SDK
• 由...驱动 Serper.dev 网络搜索功能
• 通过全面的错误处理和用户指导得到增强