MCP Inventory Redbus API

A Go application following clean architecture principles, designed for integrating with Redbus inventory system for bus ticketing services and providing MCP (Model Context Protocol) tools for Claude Desktop integration.

Project Overview

This API provides endpoints to interact with the Redbus inventory system for bus ticketing. It allows querying bus routes, getting source-destination pairs, retrieving LIS IDs, fetching detailed route information with seat details, pricing, and boarding/dropping points. Additionally, it includes MCP tools that can be used with Claude Desktop for AI-assisted bus inventory queries.

Architecture

The project follows a clean architecture pattern with the following structure:

config/: Configuration management for database, Redis, and Redbus API endpoints.
- config.go: Main configuration loader.
- type.go: Configuration type definitions.
delivery/: Handles HTTP delivery (REST API endpoints).
- api/: API response utilities.
- controller/: HTTP controllers (e.g., bus_controller.go for bus-related endpoints).
- middleware/: Middleware for authentication.
manager/: Orchestrates infrastructure and business logic.
- infra_manager.go: Manages infrastructure (MySQL database, Redis).
- repository_manager.go: Manages repository layer.
- usecase_manager.go: Manages usecase layer.
model/: Data models and DTOs (Data Transfer Objects).
- dto/: DTOs for request/response (e.g., route_details_request.go, bus_query_request.go).
- user.go: User model definition.
- bus.go: Bus-related model definitions.
repository/: Data persistence layer (e.g., bus_repository.go for database operations and API calls).
usecase/: Business logic layer (e.g., bus_usecase.go for bus-related use cases).
service/: MCP service integration.
utils/: Utility functions.
- app_error.go: Custom error handling.
- generic_sn.go: Generic utilities.
- json_io.go: JSON input/output helpers.
- app.go: Application-wide utilities.

API Endpoints

1. Get LIS Source Destination

Endpoint: POST /bus/lis-source-destination

Request:

{
  "vendor_id": "34160",
  "source_id": "CGK",
  "destination_id": "SUB"
}

Response:

{
  "status": true,
  "data": {
    "lis_source_id": "193495",
    "lis_destination_id": "194676"
  },
  "message": "Success"
}

Function: Maps vendor-specific source and destination codes to LIS (Location Information System) IDs.

2. Get Route Details Filtered

Endpoint: POST /bus/route-details-filtered

Request:

{
  "vendor_id": "34188",
  "lis_source_id": "194354",
  "lis_destination_id": "193515",
  "doj": "2025-07-30"
}

Response:

{
  "status": true,
  "data": {
    "route_details": [
      {
        "source_name": "Surabaya",
        "destination_name": "Denpasar (bali)",
        "route_id": "12745633",
        "rating": 4.53483,
        "available_seats": 13,
        "depart_time": "2025-07-30 19:00:00",
        "arrival_time": "2025-07-31 07:00:00",
        "seat_details": [
          {
            "seat_number": "1",
            "seat_type": "Seater",
            "price": 300000.0,
            "is_window": true,
            "status": "AVAILABLE"
          }
        ],
        "bp_list": [
          {
            "name": "Kota Surabaya",
            "address": "Jln. Letjen Sutoyo No.80 Surabaya"
          }
        ],
        "dp_list": [
          {
            "name": "Kantor Cokro",
            "address": "Jln.HOS.Cokroaminoto No.294 Denpasar"
          }
        ]
      }
    ]
  },
  "message": "Success"
}

Function: Provides comprehensive route details including seat information, pricing, and boarding/dropping points.

3. Get Source-Destination Pairs

Endpoint: POST /bus/sd-pairs

Request:

{
  "vendor_id": "34188"
}

Response:

{
  "status": true,
  "data": [
    {
      "source_id": "SUB",
      "source": "Surabaya",
      "destination_id": "DPS",
      "destination": "Denpasar"
    }
  ],
  "message": "Success"
}

Function: Returns all available source-destination pairs for a specific vendor.

4. Get Bus Routes (Stateless)

Endpoint: POST /bus/routesNotState

Request:

{
  "vendor_id": "34188",
  "source": "Surabaya",
  "destination": "Denpasar",
  "source_id": "SUB",
  "destination_id": "DPS",
  "date": "2025-07-30"
}

Response:

{
  "status": true,
  "data": {
    "buses": [
      {
        "service_name": "COMFORT SBY-DPS_Comfort Class",
        "departure_time": "2025-07-30 19:00:00",
        "arrival_time": "2025-07-31 07:00:00",
        "fare": 300000.0,
        "currency": "IDR",
        "available_seats": 13,
        "bus_type": "Super Executive"
      }
    ]
  },
  "message": "Success"
}

Function: Provides a summary of available buses for a specific route and date.

5. Get Vendor Cities

Endpoint: POST /bus/vendor-cities

Request:

{
  "vendor_id": "34188"
}

Response:

{
  "status": true,
  "data": {
    "cities": [
      {
        "CityId": "193495",
        "CityName": "Jakarta",
        "VCityId": "CGK"
      }
    ],
    "message": "Found 150 cities for vendor 34188"
  },
  "message": "Success"
}

Function: Returns all cities served by a specific vendor from the external Redbus API.

MCP (Model Context Protocol) Tools

The application includes MCP tools that can be used with Claude Desktop for AI-assisted bus inventory queries. The following tools are available:

busRoutes: Find available bus routes
sdPairs: Get source-destination pairs for a vendor
getLisSourceDestination: Get LIS Source and Destination IDs for a vendor route
getRouteDetailsFiltered: Get detailed route information with seat details and pricing
getVendorCities: Get all cities served by a vendor

Prerequisites

Go 1.18 or later
MySQL database
Redis for caching
Access to Redbus integration APIs
Claude Desktop (for MCP integration)

Setup

1. Clone the Repository

git clone https://github.com/Steve246/mcp-inventoryRB.git
cd mcp-inventoryRB

2. Install Dependencies

go mod download

3. Configure Environment Variables

Create a .env file in the root directory (copy from steven.env as a template):

cp steven.env .env

The .env file should contain the following variables:

# Database Configuration
DB_HOST=xxx
DB_PORT=xxx
DB_USER=xxx
DB_PASSWORD=xxx
DB_NAME=xxx

# API Configuration
API_URL=xxx

# Redis Configuration
REDIS_ADDRESS=xxx
REDIS_PASSWORD=xxx
REDIS_DB=xxx

# Redbus API Endpoints
getSdPair= getsourcedestinationpairs url
getAvRoutes= getAvRoutesObject url
getRedbusSearch= getAvRoutesObject url
getRealTime= getRealTimeUpdate url

4. Build the Application

# Build the application
go build -o mcp-server .

# Or build for production
go build -ldflags="-s -w" -o mcp-server .

5. Run the Application

# Run the full application (HTTP API + MCP server)
./mcp-server

# Or run MCP server only
./mcp-server --mcp-only

6. Access the API

The HTTP API will be available at http://localhost:8888

MCP Integration with Claude Desktop

Step-by-Step Setup Guide

1. Install Claude Desktop

Download and install Claude Desktop from https://claude.ai/download
Sign in with your Anthropic account

2. Build the MCP Server

# Navigate to your project directory
cd /path/to/mcp-inventoryRB

# Build the application
go build -o mcp-server .

# Make sure it's executable
chmod +x mcp-server

3. Configure Environment Variables

Create or copy your .env file with database credentials:

cp steven.env .env
# Edit .env with your actual database credentials

4. Locate Claude Desktop Configuration File

Find the correct path for your operating system:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json (usually C:\Users\<username>\AppData\Roaming\Claude\claude_desktop_config.json)
Linux: ~/.config/Claude/claude_desktop_config.json

5. Create or Edit the Configuration File

If the file doesn't exist, create it. Otherwise, add to the existing mcpServers object:

{
  "mcpServers": {
    "mcp-inventoryRB": {
      "command": "/absolute/path/to/mcp-server",
      "args": ["--mcp-only"],
      "env": {
        "ENV_FILE": "steven.env"
      }
    }
  }
}

Important Notes:

Use absolute paths for the command field
The --mcp-only flag runs only the MCP server (no HTTP API)
Simply specify ENV_FILE with your environment file name (defaults to "steven.env")
The MCP server will automatically load all environment variables from the specified .env file

6. Restart Claude Desktop

Completely quit Claude Desktop (Cmd+Q on Mac, Alt+F4 on Windows)
Restart the application
The MCP server should start automatically

7. Verify the Integration

Open Claude Desktop and try these test queries:

What cities does vendor 34188 serve?

Find bus routes from Jakarta to Surabaya

Show me source-destination pairs for vendor 34160

If you see responses with actual data, the integration is working!

Troubleshooting MCP Connection

MCP Server Won't Start

Check that the path to mcp-server is correct and executable
Verify your .env file exists and contains correct environment variables
Ensure the ENV_FILE environment variable points to the correct .env file
Check the Claude Desktop logs for error messages

Database Connection Issues

Ensure your .env file has correct database credentials
Test database connectivity: mysql -h DB_HOST -u DB_USER -p DB_NAME

No MCP Tools Available

Restart Claude Desktop after configuration changes
Check that the MCP server process is running: ps aux | grep mcp-server
Verify JSON syntax in claude_desktop_config.json

Permission Issues

On macOS/Linux, ensure the MCP server binary has execute permissions: chmod +x mcp-server
Check file permissions on the configuration file

MCP Tools Available

Once connected, Claude can use these tools:

busRoutes - Find available bus routes between locations
sdPairs - Get source-destination pairs for a vendor
getLisSourceDestination - Convert vendor codes to LIS system IDs
getRouteDetailsFiltered - Get detailed route information with pricing
getVendorCities - List all cities served by a vendor

Example Usage

User: "What cities does vendor 34188 serve?"
Claude: [Uses getVendorCities tool] "Vendor 34188 serves 150 cities including Jakarta, Surabaya, Bali, and more..."

User: "Find bus routes from Jakarta to Bali on December 25th"
Claude: [Uses busRoutes tool] "Here are the available bus routes from Jakarta to Bali on December 25th..."

Running MCP Server Independently

You can also run the MCP server separately for testing:

# Run only MCP server (no HTTP API)
./mcp-server --mcp-only

# Run both HTTP API and MCP server
./mcp-server

The MCP server will listen for connections from Claude Desktop via stdio protocol.

Dependencies

Gin: HTTP web framework
GORM: ORM library with MySQL driver
Redis: Caching and session management
godotenv: Environment variable loading from .env files
MCP Go Library: Model Context Protocol implementation for Claude Desktop integration

Configuration

The application uses environment variables loaded from a .env file:

Database: MySQL connection parameters (host, port, user, password, database name)
API: Server configuration (URL, port)
Redis: Caching configuration (address, password, database)
Redbus APIs: External API endpoints for bus inventory integration

Environment Variables

Variable	Description	Default
`DB_HOST`	MySQL database host	Internal URL
`DB_PORT`	MySQL database port	Internal Port
`DB_USER`	MySQL database user	Internal URL
`DB_PASSWORD`	MySQL database password	Internal Password
`DB_NAME`	MySQL database name	Internal Name
`API_URL`	HTTP server URL	Internal URL
`REDIS_ADDRESS`	Redis server address	Internal URL
`REDIS_PASSWORD`	Redis password	Internal Password
`REDIS_DB`	Redis database number	`0`
`getSdPair`	Redbus SD pairs API endpoint	Internal URL
`getAvRoutes`	Redbus available routes API endpoint	Internal URL
`getRedbusSearch`	Redbus search API endpoint	Internal URL
`getRealTime`	Redbus real-time update API endpoint	Internal URL

API Flow

Typical usage workflow:

Discover Cities: Use /bus/vendor-cities to get all cities served by a vendor
Discover Routes: Use /bus/sd-pairs to get available source-destination pairs for a vendor
Get LIS IDs: Use /bus/lis-source-destination to map vendor codes to LIS system IDs
Get Route Details: Use /bus/route-details-filtered to get comprehensive route information
Quick Search: Use /bus/routesNotState for simplified route queries

MCP Usage Examples

Once configured with Claude Desktop, you can ask natural language questions:

"Show me all cities served by vendor 34188"
"Find bus routes from Jakarta to Bali on December 25th"
"Get detailed information for route from Surabaya to Denpasar"
"What are the source-destination pairs for vendor 34160?"

Error Handling

Standard HTTP status codes:

200 OK: Successful request
400 Bad Request: Invalid request parameters
404 Not Found: Resource not found
500 Internal Server Error: Server error

Project Structure

mcp-inventoryRB/
├── app.go              # Application entry point
├── go.mod              # Go module dependencies
├── go.sum              # Go module checksums
├── steven.env          # Environment variables template
├── readme.md           # This documentation
├── config/             # Configuration management
│   ├── config.go       # Main configuration loader
│   └── type.go         # Configuration type definitions
├── delivery/           # HTTP layer
│   ├── api/           # Response utilities
│   │   └── response/  # JSON response handlers
│   ├── controller/    # HTTP controllers
│   │   └── bus_controller.go
│   ├── middleware/    # Request middleware
│   │   └── auth_token_middleware.go
│   └── server.go      # HTTP server setup
├── files/             # Legacy configuration files
├── manager/           # Infrastructure management
│   ├── infra_manager.go
│   ├── repository_manager.go
│   ├── service_manager.go
│   └── usecase_manager.go
├── model/             # Data models and DTOs
│   ├── bus.go         # Bus-related models
│   ├── bus_mcp.go     # MCP tool argument models
│   ├── user.go        # User model
│   └── dto/           # Request/response DTOs
├── repository/        # Data access layer
│   └── bus_repository.go
├── service/           # MCP service integration
│   └── mcp_service.go # MCP server implementation
├── usecase/           # Business logic layer
│   └── bus_service.go
└── utils/             # Helper utilities
    ├── app_error.go   # Custom error handling
    ├── change_format.go
    ├── generate_sn.go
    ├── json_io.go
    └── utils.go

Contributing

Follow clean architecture principles
Maintain separation of concerns between layers
Add appropriate error handling
Update documentation for new endpoints and features
Test both HTTP API and MCP tool functionality

Building and Deployment

Development Build

# Clean and build
go clean
go build -o mcp-server .

# Run tests
go test ./...

Production Build

# Optimized build with stripped symbols
go build -ldflags="-s -w" -o mcp-server .

# Cross-platform build (example for Linux)
GOOS=linux GOARCH=amd64 go build -ldflags="-s -w" -o mcp-server-linux .

Docker Build (Optional)

FROM golang:1.21-alpine AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN go build -ldflags="-s -w" -o mcp-server .

FROM alpine:latest
RUN apk --no-cache add ca-certificates
WORKDIR /root/
COPY --from=builder /app/mcp-server .
COPY --from=builder /app/steven.env .env
CMD ["./mcp-server"]

Troubleshooting

Common Issues

Database Connection Failed: Check your .env file database credentials
MCP Tools Not Available: Ensure Claude Desktop is configured with correct MCP server path
API Returns Empty Results: Verify vendor IDs and external API endpoints are accessible
Build Errors: Run go mod tidy to clean up dependencies

Debug Mode

For additional logging, you can modify the configuration to enable debug logging in your environment variables.

Name		Name	Last commit message	Last commit date
Latest commit History 23 Commits
config		config
delivery		delivery
manager		manager
model		model
repository		repository
service		service
usecase		usecase
utils		utils
.gitignore		.gitignore
app.go		app.go
go.mod		go.mod
go.sum		go.sum
mcp-server		mcp-server
readme.md		readme.md
steven.env		steven.env

Steve246/mcp-inventoryRB

Folders and files

Latest commit

History

Repository files navigation

MCP Inventory Redbus API

Project Overview

Architecture

API Endpoints

1. Get LIS Source Destination

2. Get Route Details Filtered

3. Get Source-Destination Pairs

4. Get Bus Routes (Stateless)

5. Get Vendor Cities

MCP (Model Context Protocol) Tools

Prerequisites

Setup

1. Clone the Repository

2. Install Dependencies

3. Configure Environment Variables

4. Build the Application

5. Run the Application

6. Access the API

MCP Integration with Claude Desktop

Step-by-Step Setup Guide

1. Install Claude Desktop

2. Build the MCP Server

3. Configure Environment Variables

4. Locate Claude Desktop Configuration File

5. Create or Edit the Configuration File

6. Restart Claude Desktop

7. Verify the Integration

Troubleshooting MCP Connection

MCP Server Won't Start

Database Connection Issues

No MCP Tools Available

Permission Issues

MCP Tools Available

Example Usage

Running MCP Server Independently

Dependencies

Configuration

Environment Variables

API Flow

MCP Usage Examples

Error Handling

Project Structure

Contributing

Building and Deployment

Development Build

Production Build

Docker Build (Optional)

Troubleshooting

Common Issues

Debug Mode

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages