麦普-企业流量分析

Name: 麦普-企业流量分析
Author: georgegiosue

作者：georgegiosue4 星标更新：2025-07-14

安装使用来源：spider==github.com

项目介绍

MCP Emtrafesa

一个用于访问秘鲁Emtrafesa公交运输服务的模型上下文协议（MCP）服务器。

English: README.md (您在这里)
Español: README.es.md

MCP Emtrafesa 是一个模型上下文协议服务器，它为AI助手提供了无缝访问秘鲁Emtrafesa公交运输系统的能力。通过标准化的MCP工具查询终端、时刻表、票务和常见问题。

🚀 功能

🏢 终端管理：访问秘鲁的所有公交终端
📅 时刻表查询：实时出发和到达时刻表
🎫 票务查询：按DNI和电子邮件搜索已购票
❓ 常见问题支持：访问常见问题
🔍 路线规划：查找终端之间的可用路线
🌍 秘鲁特定功能：本地化日期格式和时区处理

📦 安装

先决条件

Bun v1.2.10 或更高版本
Node.js v18+（用于TypeScript支持）

快速开始

# 克隆仓库
git clone https://github.com/georgegiosue/mcp-emtrafesa.git
cd mcp-emtrafesa

# 安装依赖
bun install

# 启动MCP服务器
bun run index.ts

# 可选：使用Model Context Protocol Inspector启动
bunx @modelcontextprotocol/inspector bun index.ts

🔧 使用方法

MCP客户端集成

配置您的MCP客户端以连接到此服务器：

{
  "mcpServers": {
    "mcp-emtrafesa": {
      "command": "npx",
      "args": ["mcp-emtrafesa@latest"]
    }
  }
}

可用工具

工具	描述	参数
`get-terminals`	获取秘鲁所有公交终端	无
`get-arrival-terminal`	获取目的地终端	`departureTerminalId`
`get-departure-schedules`	获取终端间的时刻表	`departureTerminalId`, `arrivalTerminalId`, `date?`
`get-latest-purchased-tickets`	按用户信息搜索票务	`DNI`, `email`
`get-frequently-asked-questions`	获取关于服务的常见问题	无

示例查询

// 获取所有终端
const terminals = await client.callTool("get-terminals");

// 查找从奇克拉约到特鲁希略的路线
const schedules = await client.callTool("get-departure-schedules", {
  departureTerminalId: "002",
  arrivalTerminalId: "001",
  date: "14/07/2025", // 格式：DD/MM/YYYY
});

// 查询已购票
const tickets = await client.callTool("get-latest-purchased-tickets", {
  DNI: "12345678",
  email: "user@example.com",
});

项目结构

mcp-emtrafesa/
├── 📁 config/          # API配置
│   └── api.ts          # 头部和基础设置
├── 📁 internal/        # 核心业务逻辑
│   └── emtrafesa/      # Emtrafesa特定代码
│       ├── services.ts # API客户端函数
│       └── types.ts    # TypeScript类型定义
├── 📁 sandbox/         # 开发工具
│   └── post-consulta.html # HTML解析参考
├── 📄 index.ts         # MCP服务器入口点
├── 📄 package.json     # 依赖项和脚本
├── 📄 tsconfig.json    # TypeScript配置
└── 📄 biome.json       # 代码格式规则

🛡️ API集成

支持的端点

终端：GET /Home/GetSucursales
目的地：GET /Home/GetSucursalesDestino
时刻表：POST /Home/GetItinerario (JSON)
票务：POST /Consulta/PostConsulta (表单编码)
常见问题：GET /Home/GetPreguntasFrecuentes

数据处理

JSON API：直接反序列化结构化数据
HTML抓取：基于Cheerio的票务信息解析
日期格式：秘鲁时区（America/Lima），格式为DD/MM/YYYY
错误处理：优雅降级，带有JSON错误响应

🧪 开发

代码格式化

# 使用Biome格式化代码
bun run format

# 不写入检查格式
bunx biome check

类型安全

严格的TypeScript配置，包含noUncheckedIndexedAccess
运行时验证的Zod模式
精确的API字段映射在类型定义中

测试HTML解析

使用参考文件测试更改：

# 查看HTML结构参考
open sanbox/post-consulta.html

🤝 贡献

Fork 仓库
创建特性分支 (git checkout -b feature/amazing-feature)
格式化 你的代码 (bun run format)
提交你的更改 (git commit -m '添加惊人的特性')
推送到分支 (git push origin feature/amazing-feature)
打开 Pull Request