mcp-emtrafesa 1.1.0 → 1.1.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.
Files changed (5) hide show
  1. package/README.es.md +96 -89
  2. package/README.md +96 -89
  3. package/dist/src/index.d.ts +2 -0
  4. package/dist/src/index.js +57748 -0
  5. package/package.json +2 -1
package/README.es.md CHANGED
@@ -13,23 +13,36 @@
13
13
 
14
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
15
 
16
- ## 🚀 Características
16
+ ---
17
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
18
+ ## ¿Qué puedes hacer con este MCP?
24
19
 
25
- ## 📦 Instalación
20
+ - **Buscar terminales** de buses en todo el Perú
21
+ - **Consultar horarios** entre cualquier par de ciudades
22
+ - **Ver tus boletos comprados** usando tu DNI y correo electrónico
23
+ - **Descargar tu boleto en PDF** para imprimir o compartir
24
+ - **Obtener respuestas** a preguntas frecuentes
26
25
 
27
- ### Prerrequisitos
26
+ ---
28
27
 
29
- - [Bun](https://bun.sh) v1.2.10 o superior
30
- - Node.js v18+ (para soporte de TypeScript)
28
+ ## Inicio Rápido
31
29
 
32
- ### Inicio Rápido
30
+ ### Opción 1: Usar directamente con npx (Recomendado)
31
+
32
+ Agrega a la configuración de tu cliente MCP:
33
+
34
+ ```json
35
+ {
36
+ "mcpServers": {
37
+ "mcp-emtrafesa": {
38
+ "command": "npx",
39
+ "args": ["mcp-emtrafesa@latest"]
40
+ }
41
+ }
42
+ }
43
+ ```
44
+
45
+ ### Opción 2: Clonar y ejecutar localmente
33
46
 
34
47
  ```bash
35
48
  # Clona el repositorio
@@ -41,131 +54,125 @@ bun install
41
54
 
42
55
  # Inicia el servidor MCP
43
56
  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
57
  ```
48
58
 
49
- ## 🔧 Uso
59
+ > **Tip:** Usa el Inspector MCP para depuración: `bunx @modelcontextprotocol/inspector bun index.ts`
50
60
 
51
- ### Integración con Cliente MCP
61
+ ---
52
62
 
53
- Configura tu cliente MCP para conectarse a este servidor:
63
+ ## Herramientas Disponibles
54
64
 
55
- ```json
56
- {
57
- "mcpServers": {
58
- "mcp-emtrafesa": {
59
- "command": "npx",
60
- "args": ["mcp-emtrafesa@latest"]
61
- }
62
- }
63
- }
64
- ```
65
+ | Herramienta | Descripción | Parámetros |
66
+ |-------------|-------------|------------|
67
+ | `get-terminals` | Obtiene todos los terminales de buses del Perú | Ninguno |
68
+ | `get-arrival-terminal` | Obtiene terminales de destino para un origen | `departureTerminalId` |
69
+ | `get-departure-schedules` | Obtiene horarios entre dos terminales | `departureTerminalId`, `arrivalTerminalId`, `date?` |
70
+ | `get-latest-purchased-tickets` | Busca tus boletos comprados | `DNI`, `email` |
71
+ | `download-ticket-pdf` | Descarga tu boleto como archivo PDF | `ticketCode` |
72
+ | `get-frequently-asked-questions` | Obtiene preguntas frecuentes del servicio | Ninguno |
65
73
 
66
- ### Herramientas Disponibles
74
+ ---
67
75
 
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 |
76
+ ## Ejemplos de Uso
75
77
 
76
- ### Ejemplos de Consultas
78
+ ### Obtener todos los terminales
77
79
 
78
80
  ```typescript
79
- // Obtener todos los terminales
80
81
  const terminals = await client.callTool("get-terminals");
82
+ ```
83
+
84
+ ### Buscar horarios de Chiclayo a Trujillo
81
85
 
82
- // Buscar rutas de Chiclayo a Trujillo
86
+ ```typescript
83
87
  const schedules = await client.callTool("get-departure-schedules", {
84
88
  departureTerminalId: "002",
85
89
  arrivalTerminalId: "001",
86
90
  date: "14/07/2025", // formato DD/MM/YYYY
87
91
  });
92
+ ```
93
+
94
+ ### Ver tus boletos comprados
88
95
 
89
- // Buscar boletos comprados
96
+ ```typescript
90
97
  const tickets = await client.callTool("get-latest-purchased-tickets", {
91
98
  DNI: "12345678",
92
99
  email: "usuario@ejemplo.com",
93
100
  });
94
101
  ```
95
102
 
96
- ## Estructura del Proyecto
103
+ ### Descargar tu boleto en PDF
97
104
 
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
105
+ ```typescript
106
+ const pdf = await client.callTool("download-ticket-pdf", {
107
+ ticketCode: "BP01-123456",
108
+ });
109
+ // Devuelve un PDF codificado en base64 que puedes guardar o mostrar
110
110
  ```
111
111
 
112
- ## 🛡️ Integración de API
112
+ ---
113
113
 
114
- ### Endpoints Soportados
114
+ ## Requisitos
115
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`
116
+ - [Bun](https://bun.sh) v1.2.10+ o Node.js v18+
117
+ - Un cliente compatible con MCP (Claude Desktop, etc.)
121
118
 
122
- ### Manejo de Datos
119
+ ---
120
+
121
+ ## Estructura del Proyecto
123
122
 
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
123
+ ```
124
+ mcp-emtrafesa/
125
+ ├── src/
126
+ │ ├── common/ # Herramientas y utilidades compartidas
127
+ │ ├── config/ # Configuración de API
128
+ │ ├── internal/ # Lógica de negocio (servicios, tipos)
129
+ │ └── lib/ # Utilidades auxiliares
130
+ ├── index.ts # Punto de entrada del servidor MCP
131
+ ├── package.json
132
+ └── tsconfig.json
133
+ ```
128
134
 
129
- ## 🧪 Desarrollo
135
+ ---
130
136
 
131
- ### Formateo de Código
137
+ ## Desarrollo
132
138
 
133
139
  ```bash
134
- # Formatear código con Biome
140
+ # Formatear código
135
141
  bun run format
136
142
 
137
- # Verificar formateo sin escribir
143
+ # Verificar formateo
138
144
  bunx biome check
139
145
  ```
140
146
 
141
- ### Seguridad de Tipos
147
+ ---
142
148
 
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
149
+ ## Contribuciones
146
150
 
147
- ## 🤝 Contribuciones
151
+ 1. Haz fork del repositorio
152
+ 2. Crea una rama de característica (`git checkout -b feature/nueva-caracteristica`)
153
+ 3. Formatea tu código (`bun run format`)
154
+ 4. Confirma tus cambios
155
+ 5. Abre un Pull Request
148
156
 
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
157
+ ---
155
158
 
156
- ## 📄 Licencia
159
+ ## Licencia
157
160
 
158
- Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo [LICENSE](LICENSE) para más detalles.
161
+ Licencia MIT - ver [LICENSE](LICENSE) para más detalles.
162
+
163
+ ---
159
164
 
160
165
  ## Reconocimientos
161
166
 
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
167
+ - [Emtrafesa](https://emtrafesa.pe) - Proveedor de la API de transporte
168
+ - [Model Context Protocol](https://modelcontextprotocol.io) - Especificación MCP
169
+ - [@tecncr](https://github.com/tecncr) - Insights de endpoints de API
170
+ - [Bun](https://bun.sh) - Runtime rápido de JavaScript
171
+
172
+ ---
166
173
 
167
174
  ## Soporte
168
175
 
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)
176
+ - [GitHub Issues](https://github.com/georgegiosue/mcp-emtrafesa/issues)
177
+ - [GitHub Discussions](https://github.com/georgegiosue/mcp-emtrafesa/discussions)
178
+ - Email: [peraldonamoc@gmail.com](mailto:peraldonamoc@gmail.com)
package/README.md CHANGED
@@ -13,23 +13,36 @@
13
13
 
14
14
  **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.
15
15
 
16
- ## 🚀 Features
16
+ ---
17
17
 
18
- - **🏢 Terminal Management**: Access all bus terminals across Peru
19
- - **📅 Schedule Queries**: Real-time departure and arrival schedules
20
- - **🎫 Ticket Lookup**: Search purchased tickets by DNI and email
21
- - **❓ FAQ Support**: Access frequently asked questions
22
- - **🔍 Route Planning**: Find available routes between terminals
23
- - **🌍 Peru-Specific**: Localized date formats and timezone handling
18
+ ## What can you do with this MCP?
24
19
 
25
- ## 📦 Installation
20
+ - **Find bus terminals** across Peru
21
+ - **Check schedules** between any two cities
22
+ - **Look up your purchased tickets** using your DNI and email
23
+ - **Download your ticket as PDF** for printing or sharing
24
+ - **Get answers** to frequently asked questions
26
25
 
27
- ### Prerequisites
26
+ ---
28
27
 
29
- - [Bun](https://bun.sh) v1.2.10 or higher
30
- - Node.js v18+ (for TypeScript support)
28
+ ## Quick Start
31
29
 
32
- ### Quick Start
30
+ ### Option 1: Use directly with npx (Recommended)
31
+
32
+ Add to your MCP client configuration:
33
+
34
+ ```json
35
+ {
36
+ "mcpServers": {
37
+ "mcp-emtrafesa": {
38
+ "command": "npx",
39
+ "args": ["mcp-emtrafesa@latest"]
40
+ }
41
+ }
42
+ }
43
+ ```
44
+
45
+ ### Option 2: Clone and run locally
33
46
 
34
47
  ```bash
35
48
  # Clone the repository
@@ -41,131 +54,125 @@ bun install
41
54
 
42
55
  # Start the MCP server
43
56
  bun run index.ts
44
-
45
- # Optional: Start with Model Context Protocol Inspector
46
- bunx @modelcontextprotocol/inspector bun index.ts
47
57
  ```
48
58
 
49
- ## 🔧 Usage
59
+ > **Tip:** Use the MCP Inspector for debugging: `bunx @modelcontextprotocol/inspector bun index.ts`
50
60
 
51
- ### MCP Client Integration
61
+ ---
52
62
 
53
- Configure your MCP client to connect to this server:
63
+ ## Available Tools
54
64
 
55
- ```json
56
- {
57
- "mcpServers": {
58
- "mcp-emtrafesa": {
59
- "command": "npx",
60
- "args": ["mcp-emtrafesa@latest"]
61
- }
62
- }
63
- }
64
- ```
65
+ | Tool | Description | Parameters |
66
+ |------|-------------|------------|
67
+ | `get-terminals` | Get all bus terminals in Peru | None |
68
+ | `get-arrival-terminal` | Get destination terminals for a given origin | `departureTerminalId` |
69
+ | `get-departure-schedules` | Get schedules between two terminals | `departureTerminalId`, `arrivalTerminalId`, `date?` |
70
+ | `get-latest-purchased-tickets` | Search your purchased tickets | `DNI`, `email` |
71
+ | `download-ticket-pdf` | Download your ticket as a PDF file | `ticketCode` |
72
+ | `get-frequently-asked-questions` | Get FAQs about the service | None |
65
73
 
66
- ### Available Tools
74
+ ---
67
75
 
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 |
76
+ ## Usage Examples
75
77
 
76
- ### Example Queries
78
+ ### Get all terminals
77
79
 
78
80
  ```typescript
79
- // Get all terminals
80
81
  const terminals = await client.callTool("get-terminals");
82
+ ```
83
+
84
+ ### Find schedules from Chiclayo to Trujillo
81
85
 
82
- // Find routes from Chiclayo to Trujillo
86
+ ```typescript
83
87
  const schedules = await client.callTool("get-departure-schedules", {
84
88
  departureTerminalId: "002",
85
89
  arrivalTerminalId: "001",
86
90
  date: "14/07/2025", // DD/MM/YYYY format
87
91
  });
92
+ ```
93
+
94
+ ### Look up your purchased tickets
88
95
 
89
- // Look up purchased tickets
96
+ ```typescript
90
97
  const tickets = await client.callTool("get-latest-purchased-tickets", {
91
98
  DNI: "12345678",
92
99
  email: "user@example.com",
93
100
  });
94
101
  ```
95
102
 
96
- ## Project Structure
103
+ ### Download your ticket as PDF
97
104
 
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
- ├── 📄 index.ts # MCP server entry point
107
- ├── 📄 package.json # Dependencies and scripts
108
- ├── 📄 tsconfig.json # TypeScript configuration
109
- └── 📄 biome.json # Code formatting rules
105
+ ```typescript
106
+ const pdf = await client.callTool("download-ticket-pdf", {
107
+ ticketCode: "BP01-123456",
108
+ });
109
+ // Returns a base64-encoded PDF that can be saved or displayed
110
110
  ```
111
111
 
112
- ## 🛡️ API Integration
112
+ ---
113
113
 
114
- ### Supported Endpoints
114
+ ## Requirements
115
115
 
116
- - **Terminals**: `GET /Home/GetSucursales`
117
- - **Destinations**: `GET /Home/GetSucursalesDestino`
118
- - **Schedules**: `POST /Home/GetItinerario` (JSON)
119
- - **Tickets**: `POST /Consulta/PostConsulta` (Form-encoded)
120
- - **FAQs**: `GET /Home/GetPreguntasFrecuentes`
116
+ - [Bun](https://bun.sh) v1.2.10+ or Node.js v18+
117
+ - An MCP-compatible client (Claude Desktop, etc.)
121
118
 
122
- ### Data Handling
119
+ ---
120
+
121
+ ## Project Structure
123
122
 
124
- - **JSON APIs**: Direct deserialization for structured data
125
- - **HTML Scraping**: Cheerio-based parsing for ticket information
126
- - **Date Formats**: Peru timezone (America/Lima) with DD/MM/YYYY format
127
- - **Error Handling**: Graceful degradation with JSON error responses
123
+ ```
124
+ mcp-emtrafesa/
125
+ ├── src/
126
+ │ ├── common/ # Shared tools and utilities
127
+ │ ├── config/ # API configuration
128
+ │ ├── internal/ # Core business logic (services, types)
129
+ │ └── lib/ # Helper utilities
130
+ ├── index.ts # MCP server entry point
131
+ ├── package.json
132
+ └── tsconfig.json
133
+ ```
128
134
 
129
- ## 🧪 Development
135
+ ---
130
136
 
131
- ### Code Formatting
137
+ ## Development
132
138
 
133
139
  ```bash
134
- # Format code with Biome
140
+ # Format code
135
141
  bun run format
136
142
 
137
- # Check formatting without writing
143
+ # Check formatting
138
144
  bunx biome check
139
145
  ```
140
146
 
141
- ### Type Safety
147
+ ---
142
148
 
143
- - Strict TypeScript configuration with `noUncheckedIndexedAccess`
144
- - Zod schemas for runtime validation
145
- - Exact API field mapping in type definitions
149
+ ## Contributing
146
150
 
147
- ## 🤝 Contributing
151
+ 1. Fork the repository
152
+ 2. Create a feature branch (`git checkout -b feature/new-feature`)
153
+ 3. Format your code (`bun run format`)
154
+ 4. Commit your changes
155
+ 5. Open a Pull Request
148
156
 
149
- 1. **Fork** the repository
150
- 2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)
151
- 3. **Format** your code (`bun run format`)
152
- 4. **Commit** your changes (`git commit -m 'Add amazing feature'`)
153
- 5. **Push** to the branch (`git push origin feature/amazing-feature`)
154
- 6. **Open** a Pull Request
157
+ ---
155
158
 
156
- ## 📄 License
159
+ ## License
157
160
 
158
- This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
161
+ MIT License - see [LICENSE](LICENSE) for details.
162
+
163
+ ---
159
164
 
160
165
  ## Acknowledgments
161
166
 
162
- - [Emtrafesa](https://emtrafesa.pe) for providing the transportation API
163
- - [Model Context Protocol](https://modelcontextprotocol.io) for the MCP specification
164
- - [@tecncr](https://github.com/tecncr) for API endpoint insights
165
- - [Bun](https://bun.sh) for the fast JavaScript runtime
167
+ - [Emtrafesa](https://emtrafesa.pe) - Transportation API provider
168
+ - [Model Context Protocol](https://modelcontextprotocol.io) - MCP specification
169
+ - [@tecncr](https://github.com/tecncr) - API endpoint insights
170
+ - [Bun](https://bun.sh) - Fast JavaScript runtime
171
+
172
+ ---
166
173
 
167
174
  ## Support
168
175
 
169
- - **Issues**: [GitHub Issues](https://github.com/georgegiosue/mcp-emtrafesa/issues)
170
- - **Discussions**: [GitHub Discussions](https://github.com/georgegiosue/mcp-emtrafesa/discussions)
171
- - **Email**: [peraldonamoc@gmail.com](mailto:peraldonamoc@gmail.com)
176
+ - [GitHub Issues](https://github.com/georgegiosue/mcp-emtrafesa/issues)
177
+ - [GitHub Discussions](https://github.com/georgegiosue/mcp-emtrafesa/discussions)
178
+ - Email: [peraldonamoc@gmail.com](mailto:peraldonamoc@gmail.com)
package/dist/src/index.d.ts ADDED
@@ -0,0 +1,2 @@
1
+ #!/usr/bin/env node
2
+ export {};