mcp-emtrafesa 1.0.0 → 1.0.1
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 +182 -182
- package/README.md +182 -182
- package/dist/index.d.ts +1 -0
- package/dist/index.js +1 -0
- package/package.json +4 -1
package/README.es.md
CHANGED
|
@@ -1,182 +1,182 @@
|
|
|
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.typescriptlang.org/)
|
|
6
|
-
[](https://bun.sh)
|
|
7
|
-
[](https://modelcontextprotocol.io)
|
|
8
|
-
[](https://opensource.org/licenses/MIT)
|
|
9
|
-
|
|
10
|
-
- **English**: [README.md](README.md)
|
|
11
|
-
- **Español**: [README.es.md](README.es.md) (Estás aquí)
|
|
12
|
-
|
|
13
|
-
**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.
|
|
14
|
-
|
|
15
|
-
## 🚀 Características
|
|
16
|
-
|
|
17
|
-
- **🏢 Gestión de Terminales**: Accede a todos los terminales de autobuses en todo el Perú
|
|
18
|
-
- **📅 Consulta de Horarios**: Horarios de salida y llegada en tiempo real
|
|
19
|
-
- **🎫 Búsqueda de Boletos**: Busca boletos comprados por DNI y correo electrónico
|
|
20
|
-
- **❓ Soporte de FAQ**: Accede a preguntas frecuentes
|
|
21
|
-
- **🔍 Planificación de Rutas**: Encuentra rutas disponibles entre terminales
|
|
22
|
-
- **🌍 Específico para Perú**: Formatos de fecha localizados y manejo de zona horaria
|
|
23
|
-
|
|
24
|
-
## 📦 Instalación
|
|
25
|
-
|
|
26
|
-
### Prerrequisitos
|
|
27
|
-
|
|
28
|
-
- [Bun](https://bun.sh) v1.2.10 o superior
|
|
29
|
-
- Node.js v18+ (para soporte de TypeScript)
|
|
30
|
-
|
|
31
|
-
### Inicio Rápido
|
|
32
|
-
|
|
33
|
-
```bash
|
|
34
|
-
# Clona el repositorio
|
|
35
|
-
git clone https://github.com/georgegiosue/mcp-emtrafesa.git
|
|
36
|
-
cd mcp-emtrafesa
|
|
37
|
-
|
|
38
|
-
# Instala las dependencias
|
|
39
|
-
bun install
|
|
40
|
-
|
|
41
|
-
# Inicia el servidor MCP
|
|
42
|
-
bun run index.ts
|
|
43
|
-
|
|
44
|
-
# Opcional: Inicia con el Inspector del Protocolo de Contexto de Modelo
|
|
45
|
-
bunx @modelcontextprotocol/inspector bun index.ts
|
|
46
|
-
```
|
|
47
|
-
|
|
48
|
-
## 🔧 Uso
|
|
49
|
-
|
|
50
|
-
### Integración con Cliente MCP
|
|
51
|
-
|
|
52
|
-
Configura tu cliente MCP para conectarse a este servidor:
|
|
53
|
-
|
|
54
|
-
```json
|
|
55
|
-
{
|
|
56
|
-
"mcpServers": {
|
|
57
|
-
"mcp-emtrafesa": {
|
|
58
|
-
"command": "bun",
|
|
59
|
-
"args": ["run", "index.ts"],
|
|
60
|
-
"cwd": "/ruta/a/mcp-emtrafesa"
|
|
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
|
-
├── 📁 sandbox/ # Utilidades de desarrollo
|
|
107
|
-
│ └── post-consulta.html # Referencia para análisis HTML
|
|
108
|
-
├── 📄 index.ts # Punto de entrada del servidor MCP
|
|
109
|
-
├── 📄 package.json # Dependencias y scripts
|
|
110
|
-
├── 📄 tsconfig.json # Configuración de TypeScript
|
|
111
|
-
└── 📄 biome.json # Reglas de formateo de código
|
|
112
|
-
```
|
|
113
|
-
|
|
114
|
-
## 🛡️ Integración de API
|
|
115
|
-
|
|
116
|
-
### Endpoints Soportados
|
|
117
|
-
|
|
118
|
-
- **Terminales**: `GET /Home/GetSucursales`
|
|
119
|
-
- **Destinos**: `GET /Home/GetSucursalesDestino`
|
|
120
|
-
- **Horarios**: `POST /Home/GetItinerario` (JSON)
|
|
121
|
-
- **Boletos**: `POST /Consulta/PostConsulta` (Codificado en formulario)
|
|
122
|
-
- **FAQs**: `GET /Home/GetPreguntasFrecuentes`
|
|
123
|
-
|
|
124
|
-
### Manejo de Datos
|
|
125
|
-
|
|
126
|
-
- **APIs JSON**: Deserialización directa para datos estructurados
|
|
127
|
-
- **Web Scraping HTML**: Análisis basado en Cheerio para información de boletos
|
|
128
|
-
- **Formatos de Fecha**: Zona horaria de Perú (America/Lima) con formato DD/MM/YYYY
|
|
129
|
-
- **Manejo de Errores**: Degradación elegante con respuestas de error JSON
|
|
130
|
-
|
|
131
|
-
## 🧪 Desarrollo
|
|
132
|
-
|
|
133
|
-
### Formateo de Código
|
|
134
|
-
|
|
135
|
-
```bash
|
|
136
|
-
# Formatear código con Biome
|
|
137
|
-
bun run format
|
|
138
|
-
|
|
139
|
-
# Verificar formateo sin escribir
|
|
140
|
-
bunx biome check
|
|
141
|
-
```
|
|
142
|
-
|
|
143
|
-
### Seguridad de Tipos
|
|
144
|
-
|
|
145
|
-
- Configuración estricta de TypeScript con `noUncheckedIndexedAccess`
|
|
146
|
-
- Esquemas Zod para validación en tiempo de ejecución
|
|
147
|
-
- Mapeo exacto de campos de API en definiciones de tipos
|
|
148
|
-
|
|
149
|
-
### Pruebas de Análisis HTML
|
|
150
|
-
|
|
151
|
-
Usa el archivo de referencia para probar cambios:
|
|
152
|
-
|
|
153
|
-
```bash
|
|
154
|
-
# Ver la referencia de estructura HTML
|
|
155
|
-
open sandbox/post-consulta.html
|
|
156
|
-
```
|
|
157
|
-
|
|
158
|
-
## 🤝 Contribuciones
|
|
159
|
-
|
|
160
|
-
1. **Haz fork** del repositorio
|
|
161
|
-
2. **Crea** una rama de característica (`git checkout -b feature/caracteristica-increible`)
|
|
162
|
-
3. **Formatea** tu código (`bun run format`)
|
|
163
|
-
4. **Confirma** tus cambios (`git commit -m 'Agrega característica increíble'`)
|
|
164
|
-
5. **Envía** a la rama (`git push origin feature/caracteristica-increible`)
|
|
165
|
-
6. **Abre** un Pull Request
|
|
166
|
-
|
|
167
|
-
## 📄 Licencia
|
|
168
|
-
|
|
169
|
-
Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo [LICENSE](LICENSE) para más detalles.
|
|
170
|
-
|
|
171
|
-
## Reconocimientos
|
|
172
|
-
|
|
173
|
-
- [Emtrafesa](https://emtrafesa.pe) 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.typescriptlang.org/)
|
|
6
|
+
[](https://bun.sh)
|
|
7
|
+
[](https://modelcontextprotocol.io)
|
|
8
|
+
[](https://opensource.org/licenses/MIT)
|
|
9
|
+
|
|
10
|
+
- **English**: [README.md](README.md)
|
|
11
|
+
- **Español**: [README.es.md](README.es.md) (Estás aquí)
|
|
12
|
+
|
|
13
|
+
**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.
|
|
14
|
+
|
|
15
|
+
## 🚀 Características
|
|
16
|
+
|
|
17
|
+
- **🏢 Gestión de Terminales**: Accede a todos los terminales de autobuses en todo el Perú
|
|
18
|
+
- **📅 Consulta de Horarios**: Horarios de salida y llegada en tiempo real
|
|
19
|
+
- **🎫 Búsqueda de Boletos**: Busca boletos comprados por DNI y correo electrónico
|
|
20
|
+
- **❓ Soporte de FAQ**: Accede a preguntas frecuentes
|
|
21
|
+
- **🔍 Planificación de Rutas**: Encuentra rutas disponibles entre terminales
|
|
22
|
+
- **🌍 Específico para Perú**: Formatos de fecha localizados y manejo de zona horaria
|
|
23
|
+
|
|
24
|
+
## 📦 Instalación
|
|
25
|
+
|
|
26
|
+
### Prerrequisitos
|
|
27
|
+
|
|
28
|
+
- [Bun](https://bun.sh) v1.2.10 o superior
|
|
29
|
+
- Node.js v18+ (para soporte de TypeScript)
|
|
30
|
+
|
|
31
|
+
### Inicio Rápido
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
# Clona el repositorio
|
|
35
|
+
git clone https://github.com/georgegiosue/mcp-emtrafesa.git
|
|
36
|
+
cd mcp-emtrafesa
|
|
37
|
+
|
|
38
|
+
# Instala las dependencias
|
|
39
|
+
bun install
|
|
40
|
+
|
|
41
|
+
# Inicia el servidor MCP
|
|
42
|
+
bun run index.ts
|
|
43
|
+
|
|
44
|
+
# Opcional: Inicia con el Inspector del Protocolo de Contexto de Modelo
|
|
45
|
+
bunx @modelcontextprotocol/inspector bun index.ts
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
## 🔧 Uso
|
|
49
|
+
|
|
50
|
+
### Integración con Cliente MCP
|
|
51
|
+
|
|
52
|
+
Configura tu cliente MCP para conectarse a este servidor:
|
|
53
|
+
|
|
54
|
+
```json
|
|
55
|
+
{
|
|
56
|
+
"mcpServers": {
|
|
57
|
+
"mcp-emtrafesa": {
|
|
58
|
+
"command": "bun",
|
|
59
|
+
"args": ["run", "index.ts"],
|
|
60
|
+
"cwd": "/ruta/a/mcp-emtrafesa"
|
|
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
|
+
├── 📁 sandbox/ # Utilidades de desarrollo
|
|
107
|
+
│ └── post-consulta.html # Referencia para análisis HTML
|
|
108
|
+
├── 📄 index.ts # Punto de entrada del servidor MCP
|
|
109
|
+
├── 📄 package.json # Dependencias y scripts
|
|
110
|
+
├── 📄 tsconfig.json # Configuración de TypeScript
|
|
111
|
+
└── 📄 biome.json # Reglas de formateo de código
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
## 🛡️ Integración de API
|
|
115
|
+
|
|
116
|
+
### Endpoints Soportados
|
|
117
|
+
|
|
118
|
+
- **Terminales**: `GET /Home/GetSucursales`
|
|
119
|
+
- **Destinos**: `GET /Home/GetSucursalesDestino`
|
|
120
|
+
- **Horarios**: `POST /Home/GetItinerario` (JSON)
|
|
121
|
+
- **Boletos**: `POST /Consulta/PostConsulta` (Codificado en formulario)
|
|
122
|
+
- **FAQs**: `GET /Home/GetPreguntasFrecuentes`
|
|
123
|
+
|
|
124
|
+
### Manejo de Datos
|
|
125
|
+
|
|
126
|
+
- **APIs JSON**: Deserialización directa para datos estructurados
|
|
127
|
+
- **Web Scraping HTML**: Análisis basado en Cheerio para información de boletos
|
|
128
|
+
- **Formatos de Fecha**: Zona horaria de Perú (America/Lima) con formato DD/MM/YYYY
|
|
129
|
+
- **Manejo de Errores**: Degradación elegante con respuestas de error JSON
|
|
130
|
+
|
|
131
|
+
## 🧪 Desarrollo
|
|
132
|
+
|
|
133
|
+
### Formateo de Código
|
|
134
|
+
|
|
135
|
+
```bash
|
|
136
|
+
# Formatear código con Biome
|
|
137
|
+
bun run format
|
|
138
|
+
|
|
139
|
+
# Verificar formateo sin escribir
|
|
140
|
+
bunx biome check
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
### Seguridad de Tipos
|
|
144
|
+
|
|
145
|
+
- Configuración estricta de TypeScript con `noUncheckedIndexedAccess`
|
|
146
|
+
- Esquemas Zod para validación en tiempo de ejecución
|
|
147
|
+
- Mapeo exacto de campos de API en definiciones de tipos
|
|
148
|
+
|
|
149
|
+
### Pruebas de Análisis HTML
|
|
150
|
+
|
|
151
|
+
Usa el archivo de referencia para probar cambios:
|
|
152
|
+
|
|
153
|
+
```bash
|
|
154
|
+
# Ver la referencia de estructura HTML
|
|
155
|
+
open sandbox/post-consulta.html
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
## 🤝 Contribuciones
|
|
159
|
+
|
|
160
|
+
1. **Haz fork** del repositorio
|
|
161
|
+
2. **Crea** una rama de característica (`git checkout -b feature/caracteristica-increible`)
|
|
162
|
+
3. **Formatea** tu código (`bun run format`)
|
|
163
|
+
4. **Confirma** tus cambios (`git commit -m 'Agrega característica increíble'`)
|
|
164
|
+
5. **Envía** a la rama (`git push origin feature/caracteristica-increible`)
|
|
165
|
+
6. **Abre** un Pull Request
|
|
166
|
+
|
|
167
|
+
## 📄 Licencia
|
|
168
|
+
|
|
169
|
+
Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo [LICENSE](LICENSE) para más detalles.
|
|
170
|
+
|
|
171
|
+
## Reconocimientos
|
|
172
|
+
|
|
173
|
+
- [Emtrafesa](https://emtrafesa.pe) 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)
|
package/README.md
CHANGED
|
@@ -1,182 +1,182 @@
|
|
|
1
|
-
#  MCP Emtrafesa
|
|
2
|
-
|
|
3
|
-
> A Model Context Protocol (MCP) server for accessing Emtrafesa bus transportation services in Peru
|
|
4
|
-
|
|
5
|
-
[](https://www.typescriptlang.org/)
|
|
6
|
-
[](https://bun.sh)
|
|
7
|
-
[](https://modelcontextprotocol.io)
|
|
8
|
-
[](https://opensource.org/licenses/MIT)
|
|
9
|
-
|
|
10
|
-
- **English**: [README.md](README.md) (You are here)
|
|
11
|
-
- **Español**: [README.es.md](README.es.md)
|
|
12
|
-
|
|
13
|
-
**MCP Emtrafesa** is a Model Context Protocol server that provides AI assistants with seamless access to Peru's Emtrafesa bus transportation system. Query terminals, schedules, tickets, and FAQs through standardized MCP tools.
|
|
14
|
-
|
|
15
|
-
## 🚀 Features
|
|
16
|
-
|
|
17
|
-
- **🏢 Terminal Management**: Access all bus terminals across Peru
|
|
18
|
-
- **📅 Schedule Queries**: Real-time departure and arrival schedules
|
|
19
|
-
- **🎫 Ticket Lookup**: Search purchased tickets by DNI and email
|
|
20
|
-
- **❓ FAQ Support**: Access frequently asked questions
|
|
21
|
-
- **🔍 Route Planning**: Find available routes between terminals
|
|
22
|
-
- **🌍 Peru-Specific**: Localized date formats and timezone handling
|
|
23
|
-
|
|
24
|
-
## 📦 Installation
|
|
25
|
-
|
|
26
|
-
### Prerequisites
|
|
27
|
-
|
|
28
|
-
- [Bun](https://bun.sh) v1.2.10 or higher
|
|
29
|
-
- Node.js v18+ (for TypeScript support)
|
|
30
|
-
|
|
31
|
-
### Quick Start
|
|
32
|
-
|
|
33
|
-
```bash
|
|
34
|
-
# Clone the repository
|
|
35
|
-
git clone https://github.com/georgegiosue/mcp-emtrafesa.git
|
|
36
|
-
cd mcp-emtrafesa
|
|
37
|
-
|
|
38
|
-
# Install dependencies
|
|
39
|
-
bun install
|
|
40
|
-
|
|
41
|
-
# Start the MCP server
|
|
42
|
-
bun run index.ts
|
|
43
|
-
|
|
44
|
-
# Optional: Start with Model Context Protocol Inspector
|
|
45
|
-
bunx @modelcontextprotocol/inspector bun index.ts
|
|
46
|
-
```
|
|
47
|
-
|
|
48
|
-
## 🔧 Usage
|
|
49
|
-
|
|
50
|
-
### MCP Client Integration
|
|
51
|
-
|
|
52
|
-
Configure your MCP client to connect to this server:
|
|
53
|
-
|
|
54
|
-
```json
|
|
55
|
-
{
|
|
56
|
-
"mcpServers": {
|
|
57
|
-
"mcp-emtrafesa": {
|
|
58
|
-
"command": "bun",
|
|
59
|
-
"args": ["run", "index.ts"],
|
|
60
|
-
"cwd": "/path/to/mcp-emtrafesa"
|
|
61
|
-
}
|
|
62
|
-
}
|
|
63
|
-
}
|
|
64
|
-
```
|
|
65
|
-
|
|
66
|
-
### Available Tools
|
|
67
|
-
|
|
68
|
-
| Tool | Description | Parameters |
|
|
69
|
-
| -------------------------------- | ------------------------------------ | --------------------------------------------------- |
|
|
70
|
-
| `get-terminals` | Get all bus terminals in Peru | None |
|
|
71
|
-
| `get-arrival-terminal` | Get destination terminals for origin | `departureTerminalId` |
|
|
72
|
-
| `get-departure-schedules` | Get schedules between terminals | `departureTerminalId`, `arrivalTerminalId`, `date?` |
|
|
73
|
-
| `get-latest-purchased-tickets` | Search tickets by user info | `DNI`, `email` |
|
|
74
|
-
| `get-frequently-asked-questions` | Get FAQs about the service | None |
|
|
75
|
-
|
|
76
|
-
### Example Queries
|
|
77
|
-
|
|
78
|
-
```typescript
|
|
79
|
-
// Get all terminals
|
|
80
|
-
const terminals = await client.callTool("get-terminals");
|
|
81
|
-
|
|
82
|
-
// Find routes from Chiclayo to Trujillo
|
|
83
|
-
const schedules = await client.callTool("get-departure-schedules", {
|
|
84
|
-
departureTerminalId: "002",
|
|
85
|
-
arrivalTerminalId: "001",
|
|
86
|
-
date: "14/07/2025", // DD/MM/YYYY format
|
|
87
|
-
});
|
|
88
|
-
|
|
89
|
-
// Look up purchased tickets
|
|
90
|
-
const tickets = await client.callTool("get-latest-purchased-tickets", {
|
|
91
|
-
DNI: "12345678",
|
|
92
|
-
email: "user@example.com",
|
|
93
|
-
});
|
|
94
|
-
```
|
|
95
|
-
|
|
96
|
-
## Project Structure
|
|
97
|
-
|
|
98
|
-
```
|
|
99
|
-
mcp-emtrafesa/
|
|
100
|
-
├── 📁 config/ # API configuration
|
|
101
|
-
│ └── api.ts # Headers and base settings
|
|
102
|
-
├── 📁 internal/ # Core business logic
|
|
103
|
-
│ └── emtrafesa/ # Emtrafesa-specific code
|
|
104
|
-
│ ├── services.ts # API client functions
|
|
105
|
-
│ └── types.ts # TypeScript type definitions
|
|
106
|
-
├── 📁 sandbox/ # Development utilities
|
|
107
|
-
│ └── post-consulta.html # HTML parsing reference
|
|
108
|
-
├── 📄 index.ts # MCP server entry point
|
|
109
|
-
├── 📄 package.json # Dependencies and scripts
|
|
110
|
-
├── 📄 tsconfig.json # TypeScript configuration
|
|
111
|
-
└── 📄 biome.json # Code formatting rules
|
|
112
|
-
```
|
|
113
|
-
|
|
114
|
-
## 🛡️ API Integration
|
|
115
|
-
|
|
116
|
-
### Supported Endpoints
|
|
117
|
-
|
|
118
|
-
- **Terminals**: `GET /Home/GetSucursales`
|
|
119
|
-
- **Destinations**: `GET /Home/GetSucursalesDestino`
|
|
120
|
-
- **Schedules**: `POST /Home/GetItinerario` (JSON)
|
|
121
|
-
- **Tickets**: `POST /Consulta/PostConsulta` (Form-encoded)
|
|
122
|
-
- **FAQs**: `GET /Home/GetPreguntasFrecuentes`
|
|
123
|
-
|
|
124
|
-
### Data Handling
|
|
125
|
-
|
|
126
|
-
- **JSON APIs**: Direct deserialization for structured data
|
|
127
|
-
- **HTML Scraping**: Cheerio-based parsing for ticket information
|
|
128
|
-
- **Date Formats**: Peru timezone (America/Lima) with DD/MM/YYYY format
|
|
129
|
-
- **Error Handling**: Graceful degradation with JSON error responses
|
|
130
|
-
|
|
131
|
-
## 🧪 Development
|
|
132
|
-
|
|
133
|
-
### Code Formatting
|
|
134
|
-
|
|
135
|
-
```bash
|
|
136
|
-
# Format code with Biome
|
|
137
|
-
bun run format
|
|
138
|
-
|
|
139
|
-
# Check formatting without writing
|
|
140
|
-
bunx biome check
|
|
141
|
-
```
|
|
142
|
-
|
|
143
|
-
### Type Safety
|
|
144
|
-
|
|
145
|
-
- Strict TypeScript configuration with `noUncheckedIndexedAccess`
|
|
146
|
-
- Zod schemas for runtime validation
|
|
147
|
-
- Exact API field mapping in type definitions
|
|
148
|
-
|
|
149
|
-
### Testing HTML Parsing
|
|
150
|
-
|
|
151
|
-
Use the reference file for testing changes:
|
|
152
|
-
|
|
153
|
-
```bash
|
|
154
|
-
# View the HTML structure reference
|
|
155
|
-
open sanbox/post-consulta.html
|
|
156
|
-
```
|
|
157
|
-
|
|
158
|
-
## 🤝 Contributing
|
|
159
|
-
|
|
160
|
-
1. **Fork** the repository
|
|
161
|
-
2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)
|
|
162
|
-
3. **Format** your code (`bun run format`)
|
|
163
|
-
4. **Commit** your changes (`git commit -m 'Add amazing feature'`)
|
|
164
|
-
5. **Push** to the branch (`git push origin feature/amazing-feature`)
|
|
165
|
-
6. **Open** a Pull Request
|
|
166
|
-
|
|
167
|
-
## 📄 License
|
|
168
|
-
|
|
169
|
-
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
|
170
|
-
|
|
171
|
-
## Acknowledgments
|
|
172
|
-
|
|
173
|
-
- [Emtrafesa](https://emtrafesa.pe) for providing the transportation API
|
|
174
|
-
- [Model Context Protocol](https://modelcontextprotocol.io) for the MCP specification
|
|
175
|
-
- [@tecncr](https://github.com/tecncr) for API endpoint insights
|
|
176
|
-
- [Bun](https://bun.sh) for the fast JavaScript runtime
|
|
177
|
-
|
|
178
|
-
## Support
|
|
179
|
-
|
|
180
|
-
- **Issues**: [GitHub Issues](https://github.com/georgegiosue/mcp-emtrafesa/issues)
|
|
181
|
-
- **Discussions**: [GitHub Discussions](https://github.com/georgegiosue/mcp-emtrafesa/discussions)
|
|
182
|
-
- **Email**: [peraldonamoc@gmail.com](mailto:peraldonamoc@gmail.com)
|
|
1
|
+
#  MCP Emtrafesa
|
|
2
|
+
|
|
3
|
+
> A Model Context Protocol (MCP) server for accessing Emtrafesa bus transportation services in Peru
|
|
4
|
+
|
|
5
|
+
[](https://www.typescriptlang.org/)
|
|
6
|
+
[](https://bun.sh)
|
|
7
|
+
[](https://modelcontextprotocol.io)
|
|
8
|
+
[](https://opensource.org/licenses/MIT)
|
|
9
|
+
|
|
10
|
+
- **English**: [README.md](README.md) (You are here)
|
|
11
|
+
- **Español**: [README.es.md](README.es.md)
|
|
12
|
+
|
|
13
|
+
**MCP Emtrafesa** is a Model Context Protocol server that provides AI assistants with seamless access to Peru's Emtrafesa bus transportation system. Query terminals, schedules, tickets, and FAQs through standardized MCP tools.
|
|
14
|
+
|
|
15
|
+
## 🚀 Features
|
|
16
|
+
|
|
17
|
+
- **🏢 Terminal Management**: Access all bus terminals across Peru
|
|
18
|
+
- **📅 Schedule Queries**: Real-time departure and arrival schedules
|
|
19
|
+
- **🎫 Ticket Lookup**: Search purchased tickets by DNI and email
|
|
20
|
+
- **❓ FAQ Support**: Access frequently asked questions
|
|
21
|
+
- **🔍 Route Planning**: Find available routes between terminals
|
|
22
|
+
- **🌍 Peru-Specific**: Localized date formats and timezone handling
|
|
23
|
+
|
|
24
|
+
## 📦 Installation
|
|
25
|
+
|
|
26
|
+
### Prerequisites
|
|
27
|
+
|
|
28
|
+
- [Bun](https://bun.sh) v1.2.10 or higher
|
|
29
|
+
- Node.js v18+ (for TypeScript support)
|
|
30
|
+
|
|
31
|
+
### Quick Start
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
# Clone the repository
|
|
35
|
+
git clone https://github.com/georgegiosue/mcp-emtrafesa.git
|
|
36
|
+
cd mcp-emtrafesa
|
|
37
|
+
|
|
38
|
+
# Install dependencies
|
|
39
|
+
bun install
|
|
40
|
+
|
|
41
|
+
# Start the MCP server
|
|
42
|
+
bun run index.ts
|
|
43
|
+
|
|
44
|
+
# Optional: Start with Model Context Protocol Inspector
|
|
45
|
+
bunx @modelcontextprotocol/inspector bun index.ts
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
## 🔧 Usage
|
|
49
|
+
|
|
50
|
+
### MCP Client Integration
|
|
51
|
+
|
|
52
|
+
Configure your MCP client to connect to this server:
|
|
53
|
+
|
|
54
|
+
```json
|
|
55
|
+
{
|
|
56
|
+
"mcpServers": {
|
|
57
|
+
"mcp-emtrafesa": {
|
|
58
|
+
"command": "bun",
|
|
59
|
+
"args": ["run", "index.ts"],
|
|
60
|
+
"cwd": "/path/to/mcp-emtrafesa"
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
### Available Tools
|
|
67
|
+
|
|
68
|
+
| Tool | Description | Parameters |
|
|
69
|
+
| -------------------------------- | ------------------------------------ | --------------------------------------------------- |
|
|
70
|
+
| `get-terminals` | Get all bus terminals in Peru | None |
|
|
71
|
+
| `get-arrival-terminal` | Get destination terminals for origin | `departureTerminalId` |
|
|
72
|
+
| `get-departure-schedules` | Get schedules between terminals | `departureTerminalId`, `arrivalTerminalId`, `date?` |
|
|
73
|
+
| `get-latest-purchased-tickets` | Search tickets by user info | `DNI`, `email` |
|
|
74
|
+
| `get-frequently-asked-questions` | Get FAQs about the service | None |
|
|
75
|
+
|
|
76
|
+
### Example Queries
|
|
77
|
+
|
|
78
|
+
```typescript
|
|
79
|
+
// Get all terminals
|
|
80
|
+
const terminals = await client.callTool("get-terminals");
|
|
81
|
+
|
|
82
|
+
// Find routes from Chiclayo to Trujillo
|
|
83
|
+
const schedules = await client.callTool("get-departure-schedules", {
|
|
84
|
+
departureTerminalId: "002",
|
|
85
|
+
arrivalTerminalId: "001",
|
|
86
|
+
date: "14/07/2025", // DD/MM/YYYY format
|
|
87
|
+
});
|
|
88
|
+
|
|
89
|
+
// Look up purchased tickets
|
|
90
|
+
const tickets = await client.callTool("get-latest-purchased-tickets", {
|
|
91
|
+
DNI: "12345678",
|
|
92
|
+
email: "user@example.com",
|
|
93
|
+
});
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
## Project Structure
|
|
97
|
+
|
|
98
|
+
```
|
|
99
|
+
mcp-emtrafesa/
|
|
100
|
+
├── 📁 config/ # API configuration
|
|
101
|
+
│ └── api.ts # Headers and base settings
|
|
102
|
+
├── 📁 internal/ # Core business logic
|
|
103
|
+
│ └── emtrafesa/ # Emtrafesa-specific code
|
|
104
|
+
│ ├── services.ts # API client functions
|
|
105
|
+
│ └── types.ts # TypeScript type definitions
|
|
106
|
+
├── 📁 sandbox/ # Development utilities
|
|
107
|
+
│ └── post-consulta.html # HTML parsing reference
|
|
108
|
+
├── 📄 index.ts # MCP server entry point
|
|
109
|
+
├── 📄 package.json # Dependencies and scripts
|
|
110
|
+
├── 📄 tsconfig.json # TypeScript configuration
|
|
111
|
+
└── 📄 biome.json # Code formatting rules
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
## 🛡️ API Integration
|
|
115
|
+
|
|
116
|
+
### Supported Endpoints
|
|
117
|
+
|
|
118
|
+
- **Terminals**: `GET /Home/GetSucursales`
|
|
119
|
+
- **Destinations**: `GET /Home/GetSucursalesDestino`
|
|
120
|
+
- **Schedules**: `POST /Home/GetItinerario` (JSON)
|
|
121
|
+
- **Tickets**: `POST /Consulta/PostConsulta` (Form-encoded)
|
|
122
|
+
- **FAQs**: `GET /Home/GetPreguntasFrecuentes`
|
|
123
|
+
|
|
124
|
+
### Data Handling
|
|
125
|
+
|
|
126
|
+
- **JSON APIs**: Direct deserialization for structured data
|
|
127
|
+
- **HTML Scraping**: Cheerio-based parsing for ticket information
|
|
128
|
+
- **Date Formats**: Peru timezone (America/Lima) with DD/MM/YYYY format
|
|
129
|
+
- **Error Handling**: Graceful degradation with JSON error responses
|
|
130
|
+
|
|
131
|
+
## 🧪 Development
|
|
132
|
+
|
|
133
|
+
### Code Formatting
|
|
134
|
+
|
|
135
|
+
```bash
|
|
136
|
+
# Format code with Biome
|
|
137
|
+
bun run format
|
|
138
|
+
|
|
139
|
+
# Check formatting without writing
|
|
140
|
+
bunx biome check
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
### Type Safety
|
|
144
|
+
|
|
145
|
+
- Strict TypeScript configuration with `noUncheckedIndexedAccess`
|
|
146
|
+
- Zod schemas for runtime validation
|
|
147
|
+
- Exact API field mapping in type definitions
|
|
148
|
+
|
|
149
|
+
### Testing HTML Parsing
|
|
150
|
+
|
|
151
|
+
Use the reference file for testing changes:
|
|
152
|
+
|
|
153
|
+
```bash
|
|
154
|
+
# View the HTML structure reference
|
|
155
|
+
open sanbox/post-consulta.html
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
## 🤝 Contributing
|
|
159
|
+
|
|
160
|
+
1. **Fork** the repository
|
|
161
|
+
2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)
|
|
162
|
+
3. **Format** your code (`bun run format`)
|
|
163
|
+
4. **Commit** your changes (`git commit -m 'Add amazing feature'`)
|
|
164
|
+
5. **Push** to the branch (`git push origin feature/amazing-feature`)
|
|
165
|
+
6. **Open** a Pull Request
|
|
166
|
+
|
|
167
|
+
## 📄 License
|
|
168
|
+
|
|
169
|
+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
|
170
|
+
|
|
171
|
+
## Acknowledgments
|
|
172
|
+
|
|
173
|
+
- [Emtrafesa](https://emtrafesa.pe) for providing the transportation API
|
|
174
|
+
- [Model Context Protocol](https://modelcontextprotocol.io) for the MCP specification
|
|
175
|
+
- [@tecncr](https://github.com/tecncr) for API endpoint insights
|
|
176
|
+
- [Bun](https://bun.sh) for the fast JavaScript runtime
|
|
177
|
+
|
|
178
|
+
## Support
|
|
179
|
+
|
|
180
|
+
- **Issues**: [GitHub Issues](https://github.com/georgegiosue/mcp-emtrafesa/issues)
|
|
181
|
+
- **Discussions**: [GitHub Discussions](https://github.com/georgegiosue/mcp-emtrafesa/discussions)
|
|
182
|
+
- **Email**: [peraldonamoc@gmail.com](mailto:peraldonamoc@gmail.com)
|
package/dist/index.d.ts
CHANGED
package/dist/index.js
CHANGED
package/package.json
CHANGED
|
@@ -1,11 +1,14 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "mcp-emtrafesa",
|
|
3
3
|
"description": "A Model Context Protocol (MCP) server for accessing Emtrafesa bus transportation services in Peru",
|
|
4
|
-
"version": "1.0.
|
|
4
|
+
"version": "1.0.1",
|
|
5
5
|
"module": "index.ts",
|
|
6
6
|
"main": "dist/index.js",
|
|
7
7
|
"types": "dist/index.d.ts",
|
|
8
8
|
"type": "module",
|
|
9
|
+
"bin": {
|
|
10
|
+
"mcp-emtrafesa": "dist/index.js"
|
|
11
|
+
},
|
|
9
12
|
"private": false,
|
|
10
13
|
"keywords": [
|
|
11
14
|
"mcp",
|