使用说明

MCP报价服务器

一个模型上下文协议（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小时TTL的内存缓存
- 自动缓存失效
- 重新验证模式时失效
- 用于热门查询的预热缓存
断路器
- 防止级联故障
- 自动恢复测试
- 可配置阈值
- 健康状态监测
重试逻辑
- 指数退避
- 最多3次重试尝试
- 智能错误检测
回退机制
- 过时的缓存回退
- 部分结果处理
- 优雅降级
速率限制
- 请求重复数据删除
- 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

解决方案：

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

超出费率限制

Error: Rate limit exceeded for serper

解决方案：

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

未找到报价

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

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

调试模式

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

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

贡献

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

许可证

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

致谢

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

使用说明

MCP报价服务器

特性

安装

全局安装（推荐）

或者直接与npx一起使用

快速开始

用法

运行服务器

MCP检验员测试

与Claude Desktop一起使用

对于全局安装：

或者使用npx：

使用HTTP传输

HTTP传输配置

HTTP请求示例

API

工具

getQuotes

getResilientQuotes

资源

报价提示模板

文档

发展

设置

脚本

测试

配置

建筑

高级功能

弹性模式

故障排除

常见问题

找不到SERPER_API_KEY

认证失败

超出费率限制

未找到报价

调试模式

贡献

许可证

致谢

相关 MCP

Blender 3D建模MCP服务

iOS模拟器交互服务器

网页抓取与搜索MCP服务器

B站视频搜索服务

Minecraft MCP服务器

SSH远程命令执行MCP服务器