Skip to content

Commit 19b0001

Browse files
authored
Revise README for clarity and updates
Updated README to reflect planned features and WIP status.
1 parent 9708c65 commit 19b0001

1 file changed

Lines changed: 20 additions & 205 deletions

File tree

README.md

Lines changed: 20 additions & 205 deletions
Original file line numberDiff line numberDiff line change
@@ -88,9 +88,9 @@ flowchart LR
8888
DB -->|"API Auth"| MCP
8989
MCP -->|"Timetable Data"| Tools
9090
Tools -->|"Expose MCP Tools"| TA
91-
TA --> Mobile
92-
TA --> Web
93-
TA --> Phone
91+
Mobile --> TA
92+
Web --> TA
93+
Phone --> TA
9494
9595
style Server fill:#e1f5ff,stroke:#0288d1,stroke-width:3px
9696
style API fill:#f5f5f5,stroke:#666,stroke-width:2px
@@ -100,23 +100,23 @@ flowchart LR
100100

101101
### Component Flow
102102

103-
1. **DB Timetable API** (Left)
103+
1. **DB Timetable API**
104104
- Deutsche Bahn's official timetable API
105105
- Requires API authentication
106106
- Provides schedule and real-time train data
107107

108-
2. **Timetable MCP Server** (Center) - **This Repository**
108+
2. **Timetable MCP Server** - **This Repository**
109109
- Authenticates with DB API
110110
- Fetches and processes timetable data
111111
- Exposes standardized MCP tools for agents
112112
- Implements the Model Context Protocol specification
113113

114-
3. **Timetable Agent** (Right - Not in Scope)
114+
3. **Timetable Agent** (Not in Scope)
115115
- Consumes MCP tools from this server
116116
- Orchestrates requests and responses
117117
- Interfaces with client applications
118118

119-
4. **Client Applications** (Far Right - Not in Scope)
119+
4. **Client Applications** (Not in Scope)
120120
- Mobile apps, websites, voice assistants, etc.
121121
- End-user interfaces for timetable information
122122

@@ -126,15 +126,14 @@ flowchart LR
126126

127127
## ✨ Features
128128

129-
The DB-TimetableAPI-MCPServer provides the following capabilities:
129+
The DB-TimetableAPI-MCPServer is planning to provide the following capabilities:
130130

131131
### Core Functionality
132132

133-
-**Planned Timetable Access**: Retrieve scheduled arrivals and departures for any DB station
134-
-**Real-Time Updates**: Access live delay information, cancellations, and platform changes
135-
-**Station Search**: Find stations and retrieve detailed facility information
136-
-**Train Tracking**: Follow trains across stations and routes
137-
-**Standardized MCP Interface**: Expose Deutsche Bahn data through MCP protocol
133+
- 🔜 **Planned Timetable Access**: Retrieve scheduled arrivals and departures for any DB station
134+
- 🔜 **Real-Time Updates**: Access live delay information, cancellations, and platform changes
135+
- 🔜 **Station Search**: Find stations and retrieve detailed facility information
136+
- 🔜 **Standardized MCP Interface**: Expose Deutsche Bahn data through MCP protocol
138137

139138
### Data Capabilities
140139

@@ -153,10 +152,7 @@ Before setting up the MCP server, ensure you have the following:
153152

154153
### System Requirements
155154

156-
- **Operating System**: Windows, macOS, or Linux
157-
- **Runtime**: Node.js 16+ or Python 3.8+ (depending on implementation)
158-
- **Memory**: Minimum 512MB RAM
159-
- **Network**: Stable internet connection for API access
155+
WIP
160156

161157
### DB API Access
162158

@@ -174,63 +170,17 @@ You must obtain API credentials from Deutsche Bahn:
174170

175171
## 🚀 Installation
176172

177-
### Step 1: Clone the Repository
178-
179-
```bash
180-
git clone https://github.com/abeckDev/DB-TimetableAPI-MCPServer.git
181-
cd DB-TimetableAPI-MCPServer
182-
```
183-
184-
### Step 2: Install Dependencies
185-
186-
**For Node.js implementation:**
187-
```bash
188-
npm install
189-
```
190-
191-
**For Python implementation:**
192-
```bash
193-
pip install -r requirements.txt
194-
```
195-
196-
### Step 3: Verify Installation
197-
198-
```bash
199-
# Check that all dependencies are installed
200-
npm list # or: pip list
201-
```
173+
Work in progress.
202174

203175
---
204176

205177
## ⚙️ Configuration
206178

207179
### Environment Variables
208180

209-
Create a `.env` file in the project root with the following configuration:
210-
211-
```env
212-
# Deutsche Bahn API Configuration
213-
DB_API_KEY=your_api_key_here
214-
DB_API_BASE_URL=https://apis.deutschebahn.com/db-api-marketplace/apis/timetables/v1
215-
216-
# MCP Server Configuration
217-
MCP_SERVER_PORT=3000
218-
MCP_SERVER_HOST=localhost
219-
220-
# Logging
221-
LOG_LEVEL=info
222-
```
223181

224182
### Configuration Options
225183

226-
| Variable | Description | Required | Default |
227-
|----------|-------------|----------|---------|
228-
| `DB_API_KEY` | Your Deutsche Bahn API key | Yes | - |
229-
| `DB_API_BASE_URL` | DB API endpoint URL | No | Official DB API URL |
230-
| `MCP_SERVER_PORT` | Port for MCP server | No | 3000 |
231-
| `MCP_SERVER_HOST` | Host address | No | localhost |
232-
| `LOG_LEVEL` | Logging verbosity (debug, info, warn, error) | No | info |
233-
234184
### API Rate Limits
235185

236186
Be aware of Deutsche Bahn API rate limits:
@@ -245,151 +195,27 @@ Configure appropriate caching and request throttling in your deployment.
245195

246196
### Starting the MCP Server
247197

248-
**Development Mode:**
249-
```bash
250-
npm run dev # or: python main.py --dev
251-
```
252-
253-
**Production Mode:**
254-
```bash
255-
npm start # or: python main.py
256-
```
257-
258-
The server will start and listen for MCP protocol connections on the configured port.
259-
260-
### Testing the Server
261-
262-
**Check server health:**
263-
```bash
264-
curl http://localhost:3000/health
265-
```
266-
267-
**Test MCP tool listing:**
268-
```bash
269-
curl http://localhost:3000/mcp/tools
270-
```
198+
WIP
271199

272200
### Integrating with Agents
273201

274-
To connect an AI agent to this MCP server:
275-
276-
1. Configure your MCP client with the server endpoint
277-
2. Authenticate using the MCP protocol handshake
278-
3. Query available tools using the `list_tools` method
279-
4. Invoke tools with appropriate parameters
280-
281-
**Example MCP client configuration:**
282-
```json
283-
{
284-
"mcpServers": {
285-
"db-timetable": {
286-
"command": "node",
287-
"args": ["/path/to/DB-TimetableAPI-MCPServer/index.js"],
288-
"env": {
289-
"DB_API_KEY": "your_api_key_here"
290-
}
291-
}
292-
}
293-
}
294-
```
202+
WIP
295203

296204
---
297205

298-
## 🔧 MCP Tools & Functions
206+
## 🔧 MCP Tools & Functions (Planned/Work in prgress)
299207

300208
The server exposes the following MCP tools for AI agents:
301209

302-
### `get_station_departures`
303-
Retrieve departures for a specific station.
304-
305-
**Parameters:**
306-
- `station_id` (string, required): Station identifier or name
307-
- `date` (string, optional): Date in YYYY-MM-DD format (default: today)
308-
- `time` (string, optional): Time in HH:MM format (default: now)
309-
310-
**Returns:** List of departures with train details, platforms, and delays
311-
312-
---
313-
314-
### `get_station_arrivals`
315-
Retrieve arrivals for a specific station.
316-
317-
**Parameters:**
318-
- `station_id` (string, required): Station identifier or name
319-
- `date` (string, optional): Date in YYYY-MM-DD format
320-
- `time` (string, optional): Time in HH:MM format
321-
322-
**Returns:** List of arrivals with train details and status
323-
324-
---
325-
326-
### `search_stations`
327-
Find stations by name or location.
328-
329-
**Parameters:**
330-
- `query` (string, required): Station name or search term
331-
- `limit` (number, optional): Maximum results to return (default: 10)
332-
333-
**Returns:** List of matching stations with metadata
334-
335-
---
336-
337-
### `get_train_status`
338-
Get real-time status for a specific train.
339-
340-
**Parameters:**
341-
- `train_id` (string, required): Train identifier (e.g., "ICE 123")
342-
- `date` (string, optional): Date of travel
343-
344-
**Returns:** Current train status, delays, and route information
345-
346-
---
347-
348-
### `get_station_details`
349-
Retrieve detailed information about a station.
350-
351-
**Parameters:**
352-
- `station_id` (string, required): Station identifier
353-
354-
**Returns:** Station facilities, services, and metadata
210+
WIP
355211

356212
---
357213

358214
## 🤝 Contributing
359215

360-
We welcome contributions from the community! Here's how you can help:
361-
362-
### Getting Started
363-
364-
1. **Fork the repository** on GitHub
365-
2. **Clone your fork** locally
366-
3. **Create a feature branch**: `git checkout -b feature/your-feature-name`
367-
4. **Make your changes** with clear, descriptive commits
368-
5. **Write or update tests** for your changes
369-
6. **Submit a pull request** with a detailed description
370-
371-
### Contribution Guidelines
372-
373-
- Follow existing code style and conventions
374-
- Write clear commit messages
375-
- Add tests for new features
376-
- Update documentation as needed
377-
- Ensure all tests pass before submitting PR
378-
- Keep PRs focused on a single feature or fix
379-
380-
### Code of Conduct
216+
We welcome contributions from the community!
381217

382-
- Be respectful and inclusive
383-
- Provide constructive feedback
384-
- Focus on collaboration and learning
385-
386-
### Reporting Issues
387-
388-
Found a bug or have a feature request?
389-
- Search existing issues first
390-
- Use issue templates when available
391-
- Provide detailed reproduction steps
392-
- Include relevant logs and error messages
218+
Feel free to open an issue or provide a PR.
393219

394220
---
395221

@@ -420,20 +246,9 @@ When using this software, ensure compliance with all applicable licenses and ter
420246
- [Anthropic MCP Documentation](https://www.anthropic.com/news/model-context-protocol)
421247
- [MCP Server Examples](https://github.com/modelcontextprotocol/servers)
422248

423-
### Community & Support
424-
425-
- **Issues**: [GitHub Issues](https://github.com/abeckDev/DB-TimetableAPI-MCPServer/issues)
426-
- **Discussions**: [GitHub Discussions](https://github.com/abeckDev/DB-TimetableAPI-MCPServer/discussions)
427-
- **Contact**: For questions or support, please open an issue on GitHub
428-
429249
---
430250

431251
## 🙏 Acknowledgments
432252

433253
- **Deutsche Bahn** for providing the Timetable API
434254
- **Anthropic** for developing the Model Context Protocol
435-
- All contributors to this open-source project
436-
437-
---
438-
439-
**Made with ❤️ by the open-source community**

0 commit comments

Comments
 (0)