Visa Checker MCP Server

一个专门用于实时检查签证预约可用性的MCP（模型上下文协议）服务器。

⚡ 快速开始

# 导航到你的项目
cd visa-checker-mcp

# 安装依赖项（比npm快20-30倍！）
bun install

# 运行标准I/O传输服务器
bun run dev:stdio

# 运行支持SSE的HTTP服务器
bun run dev:http

🚀 功能

🔧 现代工具

• Bun - 雷电般快速的包管理器和运行时
• TypeScript - 全面类型安全验证
• ESLint + Prettier - 代码检查和格式化
• Vitest - 快速单元测试框架

📡 签证预约检查

• 实时数据：从visasbot.com API获取实时签证预约可用性
• 智能缓存：5分钟智能缓存以减少API负载
• 错误恢复：当API不可用时自动回退到缓存数据
• 全面过滤：按国家、使馆、状态和签证类型过滤
• 丰富格式化：带有表情符号的状态指示器和详细信息

🛠️ MCP能力

• 工具：
  • fetch-visa-appointments - 获取综合预约数据并进行过滤
  • get-open-appointments - 获取仅包含可用预约的中心
  • search-visa-centers - 使用多个过滤选项进行高级搜索
• 资源：
  • visa://appointments - 完整的实时签证预约数据（JSON）
  • visa://appointments/{country_code}/{mission_code} - 按国家代码过滤的数据
• 功能：
  • 传输感知日志记录：适合stdio兼容性的正确stderr日志记录
  • Zod验证：所有参数的运行时类型检查
  • 错误处理：使用缓存数据进行优雅降级
• 符合标准：遵循官方MCP规范

📁 项目结构

visa-checker-mcp/
├── src/
│   ├── index.ts            # 主MCP服务器，包括签证工具和资源
│   ├── services/
│   │   ├── visa.ts         # 签证API客户端和数据处理
│   │   └── visa.test.ts    # 签证服务的单元测试
│   ├── config/
│   │   └── server.ts       # 服务器配置
│   └── utils/
│       └── logger.ts       # 传输感知日志记录
├── package.json            # 项目配置
├── tsconfig.json           # TypeScript配置
└── README.md               # 本文件

🎯 使用示例

签证预约检查

该服务器通过visasbot.com API提供了强大的签证预约检查功能：

可用工具：

1. fetch-visa-appointments - 获取综合签证预约数据

   // 获取所有预约
   await tool.call('fetch-visa-appointments', {})
   
   // 按国家过滤（土耳其到荷兰）
   await tool.call('fetch-visa-appointments', {
     country_code: 'tur',
     mission_code: 'nld'
   })
   
   // 按状态过滤
   await tool.call('fetch-visa-appointments', {
     status: 'open'
   })
   

2. get-open-appointments - 获取仅包含可用预约的中心

   // 获取所有开放预约
   await tool.call('get-open-appointments', {})
   
   // 按国家过滤开放预约
   await tool.call('get-open-appointments', {
     country_code: 'tur'
   })
   

3. search-visa-centers - 使用多个过滤选项进行高级搜索

   await tool.call('search-visa-centers', {
     country_code: 'tur',
     mission_code:  'nld',
     visa_type: 'tourism',
     status: 'open'
   })
   

可用资源：

• visa://appointments - 完整的实时签证预约数据（JSON）
• visa://appointments/{country_code}/{mission_code} - 按国家代码过滤的数据

特点：

• 🚀 实时数据：获取实时预约可用性
• ⚡ 智能缓存：5分钟缓存以减少API调用
• 🔍 高级过滤：按国家、使馆、状态和签证类型过滤
• 📊 丰富格式化：带有表情符号的状态指示器
• 🛡️ 错误恢复：当API不可用时自动回退到缓存数据
• ⚠️ 优雅降级：使用缓存数据时显示清晰警告
• ✅ 类型安全：使用Zod模式进行全面TypeScript验证
• 🔄 超时保护：10秒超时并有适当的错误处理

开发

# 运行标准I/O传输服务器（用于进程通信）
bun run dev:stdio

# 运行支持SSE的HTTP服务器（用于基于Web的通信）
bun run dev:http

# 类型检查
bun run typecheck

# 代码检查和格式化
bun run lint
bun run format

测试您的服务器

要测试您的MCP服务器，您可以：

1. 使用Claude Desktop：将您的服务器添加到Claude Desktop配置中
2. 使用MCP客户端库：通过stdio或HTTP编程连接
3. 手动测试：直接向服务器发送JSON-RPC消息

Claude Desktop配置示例：

{
  "mcpServers": {
    "visa-checker-mcp": {
      "command": "/path/to/bun",
      "args": ["/absolute/path/to/visa-checker-mcp/src/index.ts"]
    }
  }
}

获取正确的路径：

# 获取您的bun路径
which bun
# 示例输出：/Users/username/.bun/bin/bun

# 获取您的项目路径
echo "$(pwd)/src/index.ts"
# 示例输出：/Users/username/Dev/visa-checker-mcp/src/index.ts

完整的有效示例：

{
  "mcpServers": {
    "visa-checker-mcp": {
      "command": "/Users/username/.bun/bin/bun",
      "args": ["/Users/username/Dev/visa-checker-mcp/src/index.ts"]
    }
  }
}

🔗 传输支持

标准I/O传输

适用于本地开发和CLI工具：

• 直接进程通信
• 低延迟
• 简单调试

HTTP + SSE传输

适用于Web应用程序和远程服务：

• RESTful API端点
• 服务器发送事件（SSE）实现实时更新
• 支持CORS浏览器客户端
• 会话管理

🏗️ 开发

# 安装依赖项
bun install

# 代码检查和格式化
bun run lint
bun run format

# 构建服务器
bun run build

# 清理构建工件
bun run clean

📊 性能优势

指标	npm/Express	Bun/Hono	改进
安装速度	~15s	~2s	7.5倍更快
框架大小	~200kB	~14kB	93%更小
运行时开销	高	最小	原生TypeScript
冷启动	~500ms	~50ms	10倍更快

🤝 贡献

1. 在https://github.com/kiliczsh/visa-checker-mcp 分叉仓库
2. 创建您的功能分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m '添加惊人的功能')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 打开Pull Request

📄 许可证

本项目采用MIT许可证 - 查看LICENSE文件了解详情。

🐛 故障排除

常见问题

MCP服务器JSON解析错误 如果您看到：意外的标记 '🔧', "🔧 注册"...不是有效的JSON

这发生在使用console.log()与stdio传输时。模板使用传输感知日志记录，自动使用stderr来避免干扰stdout上的JSON-RPC消息。

Claude Desktop配置问题

1. 使用绝对路径：相对路径不起作用
2. 检查bun路径：运行which bun以获取正确的命令
3. 验证文件存在：确保TypeScript文件路径正确
4. 重启Claude Desktop：在更改配置后需要重启

类型检查错误 运行bun run typecheck以检查TypeScript问题。

服务器连接问题

1. 首先本地测试：bun run dev:stdio
2. 检查Claude Desktop日志中的错误消息
3. 确保服务器进程已启动且指定的命令/参数正确
4. 验证bun是否安装并在指定路径下可访问

路径问题

# 测试bun命令是否工作
/path/to/bun --version

# 测试您的服务器是否启动
/path/to/bun /path/to/your/project/src/index.ts

🙏 致谢

• Model Context Protocol - 本模板实现的开放标准
• Bun - 雷电般快速的JavaScript运行时和工具包
• Hono - 针对边缘的超快速Web框架