K Targo Subway MCP Server

🚀 K-Targo Subway MCP Server

This is an MCP (Model Context Protocol) server that provides subway information in South Korea.

✨ Features

• Subway Station Search: Search for subway station information by station name.
• Train Timetable Inquiry: Check the train timetable for a specific station.
• Real-time Subway Information: Provide real-time data through the Tago API.
• MCP Standard Compliance: Offer tools that adhere to the Model Context Protocol standard.

📦 Installation

Installing via Smithery

To install k-targo-subway-mcp-server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @slicequeue/k-targo-subway-mcp-server --client claude

1. Set up the Public Data API Key

This server uses the Ministry of Land, Infrastructure and Transport (TAGO) Subway Information API. You need to set up the API key before use.

API Information

• API Name: Ministry of Land, Infrastructure and Transport (TAGO) Subway Information
• API URL: https://www.data.go.kr/data/15098554/openapi.do
• Provider: Ministry of Land, Infrastructure and Transport
• Data Format: JSON

API Key Issuance

1. Sign up on the Public Data Portal.
2. Apply for the "Ministry of Land, Infrastructure and Transport (TAGO) Subway Information" API.
3. After approval, set the issued API key as an environment variable.

Environment Variable Setup

# Windows
set GOV_API_KEY=your_api_key_here

# macOS/Linux
export GOV_API_KEY=your_api_key_here

# Using .env file (recommended)
echo "GOV_API_KEY=your_api_key_here" > .env

2. Run Immediately with npx (Recommended)

npx k-targo-subway-mcp-server

3. Install with npm

npm install k-targo-subway-mcp-server

4. Global Installation

npm install -g k-targo-subway-mcp-server

💻 Usage Examples

MCP Tools

1. Subway Station Search (search_subway_station)

Search for station information by subway station name.

Input Parameters:

• stationName (string): The name of the station to search for.

Usage Example:

// Search for "Gangnam" station
const result = await searchSubwayStationTool.handler({
  stationName: "Gangnam"
}, {});

2. Train Timetable Inquiry (get_station_timetable)

Check the train timetable for a specific station.

Input Parameters:

• stationCode (string): The station code.
• direction (string): The direction (upbound/downbound).

Usage Example:

// Check the upbound timetable for Gangnam Station
const result = await getStationTimetableTool.handler({
  stationCode: "0222",
  direction: "Upbound"
}, {});

Using the MCP Client

MCP Client Configuration

To use this server in an MCP client, configure it as follows:

{
  "mcpServers": {
    "k-targo-subway": {
      "command": "npx",
      "args": ["k-targo-subway-mcp-server"],
      "env": {
        "GOV_API_KEY": "your_targo_api_key_here"
      }
    }
  }
}

Usage in the MCP Client

// Subway station search
const searchResult = await mcpClient.callTool('search_subway_station', {
  stationName: 'Gangnam'
});

// Timetable inquiry
const timetableResult = await mcpClient.callTool('get_station_timetable', {
  stationCode: '0222',
  direction: 'Upbound'
});

Running Directly from the CLI

# Run with npx (recommended)
npx k-targo-subway-mcp-server

# Run after global installation
k-targo-subway-mcp-server

# Or run with an npm script
npm start

📚 Documentation

Project Structure

src/
├── config/           # Configuration files
│   └── index.ts
├── external/         # External API integration
│   ├── common/       # Common utilities
│   └── tago-subway/  # Tago subway API
│       ├── api.ts    # API client
│       ├── service.ts # Business logic
│       ├── dtos/     # Data transfer objects
│       └── types/    # Type definitions
├── tools/           # MCP tools
│   ├── subway.ts    # Subway-related tools
│   ├── index.ts     # Tool integration
│   └── types.ts     # Tool type definitions
├── utils/           # Utilities
│   ├── PackageJsonUtil.ts
│   └── ResponseUtil.ts
└── index.ts         # Main entry point

Development Environment Setup

1. Install Dependencies

npm install

2. Set up the API Key

# Create a .env file
echo "GOV_API_KEY=your_api_key_here" > .env

# Or set it as an environment variable
export GOV_API_KEY=your_api_key_here  # macOS/Linux
set GOV_API_KEY=your_api_key_here     # Windows

Example .env File

# Ministry of Land, Infrastructure and Transport (TAGO) Subway Information API Key
# Set the API key issued from the Public Data Portal (https://www.data.go.kr/)
# API URL: https://www.data.go.kr/data/15098554/openapi.do
GOV_API_KEY=your_public_data_api_key_here

# Example:
# GOV_API_KEY=abc123def456ghi789jkl012mno345pqr678stu901vwx234yz567

3. Run the Development Server

npm run dev

4. Build

npm run build

5. Testing

# Run all tests
npm test

# API tests
npm run test:api

# Tests for a specific station
npm run test:api:station

API Integration

Ministry of Land, Infrastructure and Transport (TAGO) Subway Information API

• API Name: Ministry of Land, Infrastructure and Transport (TAGO) Subway Information
• API URL: https://www.data.go.kr/data/15098554/openapi.do
• Provider: Ministry of Land, Infrastructure and Transport
• Base URL: https://api.tago.go.kr
• Authentication: Authentication based on the public data API key (GOV_API_KEY environment variable)
• Data Format: JSON
• API Key Issuance: Apply for the "Ministry of Land, Infrastructure and Transport (TAGO) Subway Information" on the Public Data Portal.

Environment Variable Setup

# Required environment variables
GOV_API_KEY=your_public_data_api_key_here

Main Endpoints

• GET /subway-station/search: Search for subway stations.
• GET /subway-station/{stationCode}/timetable: Check the train timetable.

🔧 Technical Details

Development Workflow

1. Add New Features: Create new tool files in src/tools/.
2. API Integration: Add external API clients in src/external/.
3. Type Definitions: Define the necessary types.
4. Testing: Write test code in the test/ directory.
5. Build and Deployment: Build with npm run build and then deploy.

Key Concepts

MCP Tool

A function that users can call, consisting of an input schema and a handler function.

TAGO API

The subway information API provided by the Ministry of Land, Infrastructure and Transport, available through the Public Data Portal.

Subway Station Code

Each subway station has a unique code (e.g., Gangnam Station = "0222").

🚀 Deployment

# Build
npm run build

# Publish to npm
npm publish

# Run
node dist/index.js

📄 License

MIT License

🤝 Contributing

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📞 Contact

• GitHub: https://github.com/slicequeue/k-targo-subway-mcp-server
• Issues: https://github.com/slicequeue/k-targo-subway-mcp-server/issues

🙏 Acknowledgments

• Ministry of Land, Infrastructure and Transport (TAGO) Subway Information - Providing subway information
• Public Data Portal - Providing API services
• Model Context Protocol - MCP standard
• Node.js - Runtime environment