Visa Checker MCP

签证检查器MCP服务器

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

⚡ 快速开始

# Navigate to your project
cd visa-checker-mcp

# Install dependencies (20-30x faster than npm!)
bun install

# Run stdio transport server
bun run dev:stdio

# Run HTTP server with SSE support
bun run dev:http

🚀 特性

🔧 现代工具

• 包子 -闪电般快速的包管理器和运行时
• TypeScript -全类型安全，经过全面验证
• ESLint+Pretier -代码过滤和格式化
• 速度 -快速单元测试框架

📡 签证预约检查

• 实时数据：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} -按国家代码筛选的数据

• 特性:

- 传输感知日志记录：正确的stderr日志记录以实现stdio兼容性 - Zod验证：所有参数的运行时类型检查 - 错误处理：缓存数据回退，性能下降 - 遵从标准：遵循官方MCP规范

📁 项目结构

visa-checker-mcp/
├── src/
│   ├── index.ts            # Main MCP server with visa tools and resources
│   ├── services/
│   │   ├── visa.ts         # Visa API client and data processing
│   │   └── visa.test.ts    # Unit tests for visa service
│   ├── config/
│   │   └── server.ts       # Server configuration
│   └── utils/
│       └── logger.ts       # Transport-aware logging
├── package.json            # Project configuration
├── tsconfig.json          # TypeScript configuration
└── README.md              # This file

🎯 使用示例

签证预约检查

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

可用工具：

1. fetch-visa-appointments -获取全面的签证预约数据

   // Get all appointments
   await tool.call('fetch-visa-appointments', {})

   // Filter by country (Turkey to Netherlands)
   await tool.call('fetch-visa-appointments', {
     country_code: 'tur',
     mission_code: 'nld'
   })

   // Filter by status
   await tool.call('fetch-visa-appointments', {
     status: 'open'
   })

1. get-open-appointments -仅获取有预约的中心

   // Get all open appointments
   await tool.call('get-open-appointments', {})

   // Filter open appointments by country
   await tool.call('get-open-appointments', {
     country_code: 'tur'
   })

1. 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秒超时，正确处理错误

发展

# Run stdio transport server (for process communication)
bun run dev:stdio

# Run HTTP server with SSE support (for web-based communication)
bun run dev:http

# Type checking
bun run typecheck

# Linting and formatting
bun run lint
bun run format

测试您的服务器

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

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

Claude桌面配置示例：

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

获取正确的路径：

# Get your bun path
which bun
# Example output: /Users/username/.bun/bin/bun

# Get your project path  
echo "$(pwd)/src/index.ts"
# Example output: /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"]
    }
  }
}

🔗 运输支持

stdio运输

非常适合本地开发和CLI工具：

• 直接过程沟通
• 低延迟
• 简单调试

HTTP+SSE传输

非常适合web应用程序和远程服务：

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

🏗️ 发展

# Install dependencies
bun install

# Lint and format
bun run lint
bun run format

# Build server
bun run build

# Clean build artifacts
bun run clean

📊 性能优势

🤝 贡献

1. 在以下位置分叉存储库https://github.com/kiliczsh/visa-checker-mcp
2. 创建功能分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

📄 许可证

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

🐛 故障排除

常见问题

MCP服务器JSON解析错误 如果你看到： Unexpected token '🔧', "🔧 Registe"... is not valid JSON

当将console.log（）与stdio传输一起使用时，会发生这种情况。该模板使用传输感知日志记录，自动使用stderr进行stdio传输，以避免干扰stdout上的JSON-RPC消息。

Claude桌面配置问题

1. 使用绝对路径：相对路径不起作用
2. 检查面包路径：运行 which bun 获取正确的命令
3. 验证文件是否存在：确保TypeScript文件路径正确
4. 重新启动克劳德桌面：配置更改后需要

类型检查错误 跑 bun run typecheck 检查TypeScript问题。

服务器连接问题

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

路径问题

# Test if bun command works
/path/to/bun --version

# Test if your server starts
/path/to/bun /path/to/your/project/src/index.ts

🙏 致谢

• 模型上下文协议 -此模板实现的开放标准
• 包子 -令人难以置信的快速JavaScript运行时和工具包
• 你好 -Edges的超快web框架