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.md
CHANGED
|
@@ -1,182 +1,171 @@
|
|
|
1
|
-
#  MCP Emtrafesa
|
|
2
|
-
|
|
3
|
-
> A Model Context Protocol (MCP) server for accessing Emtrafesa bus transportation services in Peru
|
|
4
|
-
|
|
5
|
-
[ 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.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) (You are here)
|
|
12
|
+
- **EspaΓ±ol**: [README.es.md](README.es.md)
|
|
13
|
+
|
|
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
|
+
|
|
16
|
+
## π Features
|
|
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
|
|
24
|
+
|
|
25
|
+
## π¦ Installation
|
|
26
|
+
|
|
27
|
+
### Prerequisites
|
|
28
|
+
|
|
29
|
+
- [Bun](https://bun.sh) v1.2.10 or higher
|
|
30
|
+
- Node.js v18+ (for TypeScript support)
|
|
31
|
+
|
|
32
|
+
### Quick Start
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
# Clone the repository
|
|
36
|
+
git clone https://github.com/georgegiosue/mcp-emtrafesa.git
|
|
37
|
+
cd mcp-emtrafesa
|
|
38
|
+
|
|
39
|
+
# Install dependencies
|
|
40
|
+
bun install
|
|
41
|
+
|
|
42
|
+
# Start the MCP server
|
|
43
|
+
bun run index.ts
|
|
44
|
+
|
|
45
|
+
# Optional: Start with Model Context Protocol Inspector
|
|
46
|
+
bunx @modelcontextprotocol/inspector bun index.ts
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
## π§ Usage
|
|
50
|
+
|
|
51
|
+
### MCP Client Integration
|
|
52
|
+
|
|
53
|
+
Configure your MCP client to connect to this server:
|
|
54
|
+
|
|
55
|
+
```json
|
|
56
|
+
{
|
|
57
|
+
"mcpServers": {
|
|
58
|
+
"mcp-emtrafesa": {
|
|
59
|
+
"command": "npx",
|
|
60
|
+
"args": ["mcp-emtrafesa@latest"]
|
|
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
|
+
βββ π index.ts # MCP server entry point
|
|
107
|
+
βββ π package.json # Dependencies and scripts
|
|
108
|
+
βββ π tsconfig.json # TypeScript configuration
|
|
109
|
+
βββ π biome.json # Code formatting rules
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
## π‘οΈ API Integration
|
|
113
|
+
|
|
114
|
+
### Supported Endpoints
|
|
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`
|
|
121
|
+
|
|
122
|
+
### Data Handling
|
|
123
|
+
|
|
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
|
|
128
|
+
|
|
129
|
+
## π§ͺ Development
|
|
130
|
+
|
|
131
|
+
### Code Formatting
|
|
132
|
+
|
|
133
|
+
```bash
|
|
134
|
+
# Format code with Biome
|
|
135
|
+
bun run format
|
|
136
|
+
|
|
137
|
+
# Check formatting without writing
|
|
138
|
+
bunx biome check
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
### Type Safety
|
|
142
|
+
|
|
143
|
+
- Strict TypeScript configuration with `noUncheckedIndexedAccess`
|
|
144
|
+
- Zod schemas for runtime validation
|
|
145
|
+
- Exact API field mapping in type definitions
|
|
146
|
+
|
|
147
|
+
## π€ Contributing
|
|
148
|
+
|
|
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
|
|
155
|
+
|
|
156
|
+
## π License
|
|
157
|
+
|
|
158
|
+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
|
159
|
+
|
|
160
|
+
## Acknowledgments
|
|
161
|
+
|
|
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
|
|
166
|
+
|
|
167
|
+
## Support
|
|
168
|
+
|
|
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)
|
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.
|
|
5
|
-
"module": "index.ts",
|
|
6
|
-
"main": "dist/index.js",
|
|
7
|
-
"types": "dist/index.d.ts",
|
|
4
|
+
"version": "1.1.0",
|
|
5
|
+
"module": "src/index.ts",
|
|
6
|
+
"main": "dist/src/index.js",
|
|
7
|
+
"types": "dist/src/index.d.ts",
|
|
8
8
|
"type": "module",
|
|
9
|
+
"bin": {
|
|
10
|
+
"mcp-emtrafesa": "dist/src/index.js"
|
|
11
|
+
},
|
|
9
12
|
"private": false,
|
|
10
13
|
"keywords": [
|
|
11
14
|
"mcp",
|
|
@@ -31,27 +34,27 @@
|
|
|
31
34
|
"url": "git+https://github.com/georgegiosue/mcp-emtrafesa"
|
|
32
35
|
},
|
|
33
36
|
"files": [
|
|
34
|
-
"dist/*.js",
|
|
35
|
-
"dist/*.d.ts"
|
|
37
|
+
"dist/src/*.js",
|
|
38
|
+
"dist/src/*.d.ts"
|
|
36
39
|
],
|
|
37
40
|
"scripts": {
|
|
38
|
-
"build": "bun build --target=node ./index.ts --outfile=dist/index.js && bun run build:declaration",
|
|
41
|
+
"build": "bun build --target=node ./src/index.ts --outfile=dist/src/index.js && bun run build:declaration",
|
|
39
42
|
"build:declaration": "tsc --emitDeclarationOnly --project tsconfig.types.json",
|
|
40
43
|
"format": "bunx biome check --write",
|
|
41
44
|
"prepare": "husky",
|
|
42
|
-
"inspect": "bunx @modelcontextprotocol/inspector bun index.ts"
|
|
45
|
+
"inspect": "bunx @modelcontextprotocol/inspector bun src/index.ts"
|
|
43
46
|
},
|
|
44
47
|
"devDependencies": {
|
|
45
|
-
"@biomejs/biome": "2.
|
|
46
|
-
"@types/bun": "1.
|
|
48
|
+
"@biomejs/biome": "2.3.10",
|
|
49
|
+
"@types/bun": "1.3.5",
|
|
47
50
|
"husky": "9.1.7"
|
|
48
51
|
},
|
|
49
52
|
"peerDependencies": {
|
|
50
|
-
"typescript": "
|
|
53
|
+
"typescript": "5.8.3"
|
|
51
54
|
},
|
|
52
55
|
"dependencies": {
|
|
53
|
-
"@modelcontextprotocol/sdk": "1.
|
|
54
|
-
"cheerio": "1.1.
|
|
56
|
+
"@modelcontextprotocol/sdk": "1.25.1",
|
|
57
|
+
"cheerio": "1.1.2",
|
|
55
58
|
"zod": "3.25.76"
|
|
56
59
|
}
|
|
57
60
|
}
|
package/dist/index.d.ts
DELETED
|
@@ -1 +0,0 @@
|
|
|
1
|
-
export {};
|