Bangalore BMTC Mobility Connectivity Platform

# Bengaluru BMTC MCP Server An implementation of a Model Context Protocol (MCP) server for Bangalore Metropolitan Transport Corporation (BMTC) bus services. ## Architecture The BMTC MCP server follows a modular, layered architecture. The system is designed to handle real-time transit data from Bangalore Metropolitan Transport Corporation buses and provide it through a standardized API. ### Core Components 1. **API Layer**: RESTful endpoints for authentication, routes, stops, bus locations, and ETA information 2. **Service Layer**: Business logic, data transformation, and ETA calculations 3. **Data Access Layer**: MongoDB integration via Mongoose ODM 4. **Caching Layer**: Redis-based caching for improved performance 5. **External Integration Layer**: BMTC API integration [Read the full architecture documentation](docs/architecture.md) ## Features Here're the list of things that you can find using MCP Client or chat window: - Real-time bus location tracking - Route information and scheduling - Stop details and ETA (Estimated Time of Arrival) - Support for over 2,200 bus routes and 8,400+ bus stops in Bengaluru - Authentication and authorization - Data caching and optimization - GeoSpatial queries for nearby stops and buses ## Prerequisites - Node.js (v14 or later) - npm or yarn - MongoDB - Redis (optional, for caching) - Git ## Installation and Setup ### Method 1: Standard Installation 1. **Clone the repository** ```bash git clone https://github.com/ajeetraina/bengaluru-bmtc-mcp.git cd bengaluru-bmtc-mcp ``` 2. **Install dependencies** ```bash npm install ``` 3. **Configure environment variables** ```bash cp .env.example .env ``` Edit the `.env` file with your configuration: ``` PORT=3000 NODE_ENV=development MONGO_URI=mongodb://localhost:27017/bmtc-mcp REDIS_URI=redis://localhost:6379 API_KEY=your_api_key_here JWT_SECRET=your_jwt_secret_here JWT_EXPIRES_IN=86400 BMTC_API_ENDPOINT=https://bmtc-api-endpoint.example BMTC_API_KEY=your_bmtc_api_key_here CACHE_DURATION=300 LOG_LEVEL=info ``` 4. **Seed the database with mock data (optional)** ```bash node src/scripts/seed.js ``` 5. **Start the server** ```bash npm start ``` For development with auto-restart: ```bash npm run dev ``` ### Method 2: Using Docker Compose 1. **Clone the repository** ```bash git clone https://github.com/ajeetraina/bengaluru-bmtc-mcp.git cd bengaluru-bmtc-mcp ``` 2. **Configure environment variables (optional)** You can modify the environment variables directly in the `docker-compose.yml` file or create a `.env` file: ```bash cp .env.example .env ``` 3. **Build and start the containers** ```bash docker-compose up -d ``` This will start three containers: - `bmtc-mcp-api`: The Node.js API server - `bmtc-mcp-mongo`: MongoDB database - `bmtc-mcp-redis`: Redis cache server 4. **Seed the database with mock data (optional)** ```bash docker-compose exec api node src/scripts/seed.js ``` 5. **View logs** ```bash docker-compose logs -f api ``` 6. **Stop the containers** ```bash docker-compose down ``` To remove volumes as well: ```bash docker-compose down -v ``` ## Using the API Once the server is running, you can access the API at: ``` http://localhost:3000/api/v1 ``` For API documentation, visit: ``` http://localhost:3000/api-docs ``` ### Example API Endpoints ``` # Authentication POST /api/v1/auth/login GET /api/v1/auth/me # Routes GET /api/v1/routes GET /api/v1/routes/:routeId GET /api/v1/routes/search?source=Kempegowda&destination=Electronic # Stops GET /api/v1/stops GET /api/v1/stops/:stopId GET /api/v1/stops/near?lat=12.9767&lng=77.5713&radius=500 GET /api/v1/stops/search?query=Lalbagh # Bus Locations GET /api/v1/bus-locations GET /api/v1/bus-locations/:busId GET /api/v1/bus-locations/near?lat=12.9767&lng=77.5713&radius=1000 # ETA GET /api/v1/eta/:stopId GET /api/v1/eta/:stopId/:routeId ``` ## API Keys ### JWT Secret The JWT secret is used for signing authentication tokens. Generate a secure random string: ```bash node -e "console.log(require('crypto').randomBytes(32).toString('hex'))" ``` Add this to your `.env` file: ``` JWT_SECRET=your_generated_secret_here ``` ### BMTC API Key For development, you can use mock data without an actual BMTC API key: ``` BMTC_API_ENDPOINT=https://bmtc-api-endpoint.example BMTC_API_KEY=your_bmtc_api_key_here ``` For production, you would need to contact BMTC directly to request official API access. ## Development ### Testing Run the tests: ```bash npm test ``` Run tests with coverage: ```bash npm run test:coverage ``` ### Linting Check code style: ```bash npm run lint ``` Fix code style issues: ```bash npm run lint:fix ``` ### Project Structure ``` bengaluru-bmtc-mcp/ ├── .env.example # Environment variables template ├── .eslintrc.json # ESLint configuration ├── .github/ # GitHub configuration │ └── workflows/ # GitHub Actions workflows ├── .gitignore # Git ignore file ├── CONTRIBUTING.md # Contribution guidelines ├── Dockerfile # Docker configuration ├── LICENSE # MIT License ├── README.md # Project documentation ├── docker-compose.yml # Docker Compose configuration ├── docs/ # Documentation │ ├── api.md # API documentation │ └── setup.md # Setup guide ├── jest.config.js # Jest configuration ├── package.json # Project dependencies └── src/ # Source code ├── config/ # Configuration files ├── controllers/ # Request handlers ├── index.js # Application entry point ├── middlewares/ # Express middlewares ├── models/ # MongoDB models ├── public/ # Static files ├── routes/ # API routes ├── scripts/ # Utility scripts ├── services/ # External service integrations ├── tests/ # Test files └── utils/ # Utility functions ``` ## Contributing Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests. ## License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. ## Acknowledgements - [Bangalore Metropolitan Transport Corporation (BMTC)](https://mybmtc.karnataka.gov.in) - [Singapore LTA MCP Implementation](https://github.com/arjunkmrm/mcp-sg-lta) for inspiration