bengaluru-bmtc-mcp

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

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

git clone https://github.com/ajeetraina/bengaluru-bmtc-mcp.git
cd bengaluru-bmtc-mcp

2. Install dependencies

npm install

3. Configure environment variables

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)

node src/scripts/seed.js

5. Start the server

npm start

For development with auto-restart:

npm run dev

Method 2: Using Docker Compose

1. Clone the repository

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:

cp .env.example .env

3. Build and start the containers

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)

docker-compose exec api node src/scripts/seed.js

5. View logs

docker-compose logs -f api

6. Stop the containers

docker-compose down

To remove volumes as well:

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:

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:

npm test

Run tests with coverage:

npm run test:coverage

Linting

Check code style:

npm run lint

Fix code style issues:

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 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 file for details.

Acknowledgements

• Bangalore Metropolitan Transport Corporation (BMTC)
• Singapore LTA MCP Implementation for inspiration