mcp-emtrafesa 1.0.0 → 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.es.md +171 -182
- package/README.md +171 -182
- package/package.json +16 -13
- package/dist/index.d.ts +0 -1
- package/dist/index.js +0 -53883
package/README.es.md
CHANGED
|
@@ -1,182 +1,171 @@
|
|
|
1
|
-
#  MCP Emtrafesa
|
|
2
|
-
|
|
3
|
-
> Un servidor del Protocolo de Contexto de Modelo (MCP) para acceder a los servicios de transporte de autobuses de Emtrafesa en Perú
|
|
4
|
-
|
|
5
|
-
[ por proporcionar la API de transporte
|
|
174
|
-
- [Model Context Protocol](https://modelcontextprotocol.io) por la especificación MCP
|
|
175
|
-
- [@tecncr](https://github.com/tecncr) por los insights de endpoints de API
|
|
176
|
-
- [Bun](https://bun.sh) por el runtime rápido de JavaScript
|
|
177
|
-
|
|
178
|
-
## Soporte
|
|
179
|
-
|
|
180
|
-
- **Issues**: [GitHub Issues](https://github.com/georgegiosue/mcp-emtrafesa/issues)
|
|
181
|
-
- **Discusiones**: [GitHub Discussions](https://github.com/georgegiosue/mcp-emtrafesa/discussions)
|
|
182
|
-
- **Email**: [peraldonamoc@gmail.com](mailto:peraldonamoc@gmail.com)
|
|
1
|
+
#  MCP Emtrafesa
|
|
2
|
+
|
|
3
|
+
> Un servidor del Protocolo de Contexto de Modelo (MCP) para acceder a los servicios de transporte de autobuses de Emtrafesa en Perú
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/mcp-emtrafesa)
|
|
6
|
+
[](https://www.typescriptlang.org/)
|
|
7
|
+
[](https://bun.sh)
|
|
8
|
+
[](https://modelcontextprotocol.io)
|
|
9
|
+
[](https://opensource.org/licenses/MIT)
|
|
10
|
+
|
|
11
|
+
- **English**: [README.md](README.md)
|
|
12
|
+
- **Español**: [README.es.md](README.es.md) (Estás aquí)
|
|
13
|
+
|
|
14
|
+
**MCP Emtrafesa** es un servidor del Protocolo de Contexto de Modelo que proporciona a los asistentes de IA acceso fluido al sistema de transporte de autobuses Emtrafesa de Perú. Consulta terminales, horarios, boletos y preguntas frecuentes a través de herramientas MCP estandarizadas.
|
|
15
|
+
|
|
16
|
+
## 🚀 Características
|
|
17
|
+
|
|
18
|
+
- **🏢 Gestión de Terminales**: Accede a todos los terminales de autobuses en todo el Perú
|
|
19
|
+
- **📅 Consulta de Horarios**: Horarios de salida y llegada en tiempo real
|
|
20
|
+
- **🎫 Búsqueda de Boletos**: Busca boletos comprados por DNI y correo electrónico
|
|
21
|
+
- **❓ Soporte de FAQ**: Accede a preguntas frecuentes
|
|
22
|
+
- **🔍 Planificación de Rutas**: Encuentra rutas disponibles entre terminales
|
|
23
|
+
- **🌍 Específico para Perú**: Formatos de fecha localizados y manejo de zona horaria
|
|
24
|
+
|
|
25
|
+
## 📦 Instalación
|
|
26
|
+
|
|
27
|
+
### Prerrequisitos
|
|
28
|
+
|
|
29
|
+
- [Bun](https://bun.sh) v1.2.10 o superior
|
|
30
|
+
- Node.js v18+ (para soporte de TypeScript)
|
|
31
|
+
|
|
32
|
+
### Inicio Rápido
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
# Clona el repositorio
|
|
36
|
+
git clone https://github.com/georgegiosue/mcp-emtrafesa.git
|
|
37
|
+
cd mcp-emtrafesa
|
|
38
|
+
|
|
39
|
+
# Instala las dependencias
|
|
40
|
+
bun install
|
|
41
|
+
|
|
42
|
+
# Inicia el servidor MCP
|
|
43
|
+
bun run index.ts
|
|
44
|
+
|
|
45
|
+
# Opcional: Inicia con el Inspector del Protocolo de Contexto de Modelo
|
|
46
|
+
bunx @modelcontextprotocol/inspector bun index.ts
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
## 🔧 Uso
|
|
50
|
+
|
|
51
|
+
### Integración con Cliente MCP
|
|
52
|
+
|
|
53
|
+
Configura tu cliente MCP para conectarse a este servidor:
|
|
54
|
+
|
|
55
|
+
```json
|
|
56
|
+
{
|
|
57
|
+
"mcpServers": {
|
|
58
|
+
"mcp-emtrafesa": {
|
|
59
|
+
"command": "npx",
|
|
60
|
+
"args": ["mcp-emtrafesa@latest"]
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
### Herramientas Disponibles
|
|
67
|
+
|
|
68
|
+
| Herramienta | Descripción | Parámetros |
|
|
69
|
+
| -------------------------------- | -------------------------------------------------- | --------------------------------------------------- |
|
|
70
|
+
| `get-terminals` | Obtiene todos los terminales de autobuses del Perú | Ninguno |
|
|
71
|
+
| `get-arrival-terminal` | Obtiene terminales de destino para origen | `departureTerminalId` |
|
|
72
|
+
| `get-departure-schedules` | Obtiene horarios entre terminales | `departureTerminalId`, `arrivalTerminalId`, `date?` |
|
|
73
|
+
| `get-latest-purchased-tickets` | Busca boletos por información del usuario | `DNI`, `email` |
|
|
74
|
+
| `get-frequently-asked-questions` | Obtiene FAQs sobre el servicio | Ninguno |
|
|
75
|
+
|
|
76
|
+
### Ejemplos de Consultas
|
|
77
|
+
|
|
78
|
+
```typescript
|
|
79
|
+
// Obtener todos los terminales
|
|
80
|
+
const terminals = await client.callTool("get-terminals");
|
|
81
|
+
|
|
82
|
+
// Buscar rutas de Chiclayo a Trujillo
|
|
83
|
+
const schedules = await client.callTool("get-departure-schedules", {
|
|
84
|
+
departureTerminalId: "002",
|
|
85
|
+
arrivalTerminalId: "001",
|
|
86
|
+
date: "14/07/2025", // formato DD/MM/YYYY
|
|
87
|
+
});
|
|
88
|
+
|
|
89
|
+
// Buscar boletos comprados
|
|
90
|
+
const tickets = await client.callTool("get-latest-purchased-tickets", {
|
|
91
|
+
DNI: "12345678",
|
|
92
|
+
email: "usuario@ejemplo.com",
|
|
93
|
+
});
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
## Estructura del Proyecto
|
|
97
|
+
|
|
98
|
+
```
|
|
99
|
+
mcp-emtrafesa/
|
|
100
|
+
├── 📁 config/ # Configuración de API
|
|
101
|
+
│ └── api.ts # Cabeceras y configuraciones base
|
|
102
|
+
├── 📁 internal/ # Lógica de negocio principal
|
|
103
|
+
│ └── emtrafesa/ # Código específico de Emtrafesa
|
|
104
|
+
│ ├── services.ts # Funciones del cliente API
|
|
105
|
+
│ └── types.ts # Definiciones de tipos TypeScript
|
|
106
|
+
├── 📄 index.ts # Punto de entrada del servidor MCP
|
|
107
|
+
├── 📄 package.json # Dependencias y scripts
|
|
108
|
+
├── 📄 tsconfig.json # Configuración de TypeScript
|
|
109
|
+
└── 📄 biome.json # Reglas de formateo de código
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
## 🛡️ Integración de API
|
|
113
|
+
|
|
114
|
+
### Endpoints Soportados
|
|
115
|
+
|
|
116
|
+
- **Terminales**: `GET /Home/GetSucursales`
|
|
117
|
+
- **Destinos**: `GET /Home/GetSucursalesDestino`
|
|
118
|
+
- **Horarios**: `POST /Home/GetItinerario` (JSON)
|
|
119
|
+
- **Boletos**: `POST /Consulta/PostConsulta` (Codificado en formulario)
|
|
120
|
+
- **FAQs**: `GET /Home/GetPreguntasFrecuentes`
|
|
121
|
+
|
|
122
|
+
### Manejo de Datos
|
|
123
|
+
|
|
124
|
+
- **APIs JSON**: Deserialización directa para datos estructurados
|
|
125
|
+
- **Web Scraping HTML**: Análisis basado en Cheerio para información de boletos
|
|
126
|
+
- **Formatos de Fecha**: Zona horaria de Perú (America/Lima) con formato DD/MM/YYYY
|
|
127
|
+
- **Manejo de Errores**: Degradación elegante con respuestas de error JSON
|
|
128
|
+
|
|
129
|
+
## 🧪 Desarrollo
|
|
130
|
+
|
|
131
|
+
### Formateo de Código
|
|
132
|
+
|
|
133
|
+
```bash
|
|
134
|
+
# Formatear código con Biome
|
|
135
|
+
bun run format
|
|
136
|
+
|
|
137
|
+
# Verificar formateo sin escribir
|
|
138
|
+
bunx biome check
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
### Seguridad de Tipos
|
|
142
|
+
|
|
143
|
+
- Configuración estricta de TypeScript con `noUncheckedIndexedAccess`
|
|
144
|
+
- Esquemas Zod para validación en tiempo de ejecución
|
|
145
|
+
- Mapeo exacto de campos de API en definiciones de tipos
|
|
146
|
+
|
|
147
|
+
## 🤝 Contribuciones
|
|
148
|
+
|
|
149
|
+
1. **Haz fork** del repositorio
|
|
150
|
+
2. **Crea** una rama de característica (`git checkout -b feature/caracteristica-increible`)
|
|
151
|
+
3. **Formatea** tu código (`bun run format`)
|
|
152
|
+
4. **Confirma** tus cambios (`git commit -m 'Agrega característica increíble'`)
|
|
153
|
+
5. **Envía** a la rama (`git push origin feature/caracteristica-increible`)
|
|
154
|
+
6. **Abre** un Pull Request
|
|
155
|
+
|
|
156
|
+
## 📄 Licencia
|
|
157
|
+
|
|
158
|
+
Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo [LICENSE](LICENSE) para más detalles.
|
|
159
|
+
|
|
160
|
+
## Reconocimientos
|
|
161
|
+
|
|
162
|
+
- [Emtrafesa](https://emtrafesa.pe) por proporcionar la API de transporte
|
|
163
|
+
- [Model Context Protocol](https://modelcontextprotocol.io) por la especificación MCP
|
|
164
|
+
- [@tecncr](https://github.com/tecncr) por los insights de endpoints de API
|
|
165
|
+
- [Bun](https://bun.sh) por el runtime rápido de JavaScript
|
|
166
|
+
|
|
167
|
+
## Soporte
|
|
168
|
+
|
|
169
|
+
- **Issues**: [GitHub Issues](https://github.com/georgegiosue/mcp-emtrafesa/issues)
|
|
170
|
+
- **Discusiones**: [GitHub Discussions](https://github.com/georgegiosue/mcp-emtrafesa/discussions)
|
|
171
|
+
- **Email**: [peraldonamoc@gmail.com](mailto:peraldonamoc@gmail.com)
|