{"id":30272077,"url":"https://github.com/slicequeue/k-targo-subway-mcp-server","last_synced_at":"2025-08-16T05:13:14.040Z","repository":{"id":307806484,"uuid":"1030775061","full_name":"slicequeue/k-targo-subway-mcp-server","owner":"slicequeue","description":null,"archived":false,"fork":false,"pushed_at":"2025-08-02T10:46:48.000Z","size":156,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-02T11:03:00.057Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/slicequeue.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-02T09:48:19.000Z","updated_at":"2025-08-02T10:46:51.000Z","dependencies_parsed_at":"2025-08-02T11:03:01.642Z","dependency_job_id":"938a9342-f799-4734-a844-f29b54d0dcfd","html_url":"https://github.com/slicequeue/k-targo-subway-mcp-server","commit_stats":null,"previous_names":["slicequeue/k-targo-subway-mcp-server"],"tags_count":null,"template":false,"template_full_name":"slicequeue/nodets-mcp-using-sdk-boilerplate","purl":"pkg:github/slicequeue/k-targo-subway-mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slicequeue%2Fk-targo-subway-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slicequeue%2Fk-targo-subway-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slicequeue%2Fk-targo-subway-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slicequeue%2Fk-targo-subway-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/slicequeue","download_url":"https://codeload.github.com/slicequeue/k-targo-subway-mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slicequeue%2Fk-targo-subway-mcp-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270670063,"owners_count":24625444,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-16T02:00:11.002Z","response_time":91,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-16T05:13:13.122Z","updated_at":"2025-08-16T05:13:14.021Z","avatar_url":"https://github.com/slicequeue.png","language":"TypeScript","funding_links":[],"categories":["목록 (List)"],"sub_categories":["📊 Public Data"],"readme":"# 🇰🇷 K-Targo Subway MCP Server\n[![smithery badge](https://smithery.ai/badge/@slicequeue/k-targo-subway-mcp-server)](https://smithery.ai/server/@slicequeue/k-targo-subway-mcp-server)\n\n한국 지하철 정보를 제공하는 MCP (Model Context Protocol) 서버입니다.\n\n## 🚇 주요 기능\n\n- **지하철역 검색**: 역명으로 지하철역 정보 검색\n- **열차 시간표 조회**: 특정 역의 열차 시간표 조회\n- **실시간 지하철 정보**: Tago API를 통한 실시간 데이터 제공\n- **MCP 표준 준수**: Model Context Protocol 표준을 따르는 도구 제공\n\n## 🛠️ 설치 및 사용\n\n### Installing via Smithery\n\nTo install k-targo-subway-mcp-server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@slicequeue/k-targo-subway-mcp-server):\n\n```bash\nnpx -y @smithery/cli install @slicequeue/k-targo-subway-mcp-server --client claude\n```\n\n### 1. 공공데이터 API 키 설정\n이 서버는 **국토교통부_(TAGO)_지하철정보** API를 사용합니다. 사용하기 전에 API 키를 설정해야 합니다.\n\n#### API 정보\n- **API 명**: 국토교통부_(TAGO)_지하철정보\n- **API URL**: https://www.data.go.kr/data/15098554/openapi.do\n- **제공기관**: 국토교통부\n- **데이터 형식**: JSON\n\n#### API 키 발급\n1. [공공데이터포털](https://www.data.go.kr/)에 가입\n2. \"국토교통부_(TAGO)_지하철정보\" API 신청\n3. 승인 후 발급받은 API 키를 환경변수로 설정\n\n#### 환경변수 설정\n```bash\n# Windows\nset GOV_API_KEY=your_api_key_here\n\n# macOS/Linux\nexport GOV_API_KEY=your_api_key_here\n\n# .env 파일 사용 (권장)\necho \"GOV_API_KEY=your_api_key_here\" \u003e .env\n```\n\n### 2. npx로 즉시 실행 (권장)\n```bash\nnpx k-targo-subway-mcp-server\n```\n\n### 3. npm으로 설치\n```bash\nnpm install k-targo-subway-mcp-server\n```\n\n### 4. 글로벌 설치\n```bash\nnpm install -g k-targo-subway-mcp-server\n```\n\n## 📦 MCP 도구\n\n### 1. 지하철역 검색 (`search_subway_station`)\n지하철역명으로 역 정보를 검색합니다.\n\n**입력 파라미터:**\n- `stationName` (string): 검색할 역명\n\n**사용 예시:**\n```typescript\n// \"강남\" 역 검색\nconst result = await searchSubwayStationTool.handler({\n  stationName: \"강남\"\n}, {});\n```\n\n### 2. 열차 시간표 조회 (`get_station_timetable`)\n특정 역의 열차 시간표를 조회합니다.\n\n**입력 파라미터:**\n- `stationCode` (string): 역 코드\n- `direction` (string): 방향 (상행/하행)\n\n**사용 예시:**\n```typescript\n// 강남역 상행 시간표 조회\nconst result = await getStationTimetableTool.handler({\n  stationCode: \"0222\",\n  direction: \"상행\"\n}, {});\n```\n\n## 🏗️ 프로젝트 구조\n\n```\nsrc/\n├── config/           # 설정 파일\n│   └── index.ts\n├── external/         # 외부 API 연동\n│   ├── common/       # 공통 유틸리티\n│   └── tago-subway/  # Tago 지하철 API\n│       ├── api.ts    # API 클라이언트\n│       ├── service.ts # 비즈니스 로직\n│       ├── dtos/     # 데이터 전송 객체\n│       └── types/    # 타입 정의\n├── tools/           # MCP 도구들\n│   ├── subway.ts    # 지하철 관련 도구\n│   ├── index.ts     # 도구들 통합\n│   └── types.ts     # 도구 타입 정의\n├── utils/           # 유틸리티\n│   ├── PackageJsonUtil.ts\n│   └── ResponseUtil.ts\n└── index.ts         # 메인 진입점\n```\n\n## 🔧 개발 환경 설정\n\n### 1. 의존성 설치\n```bash\nnpm install\n```\n\n### 2. API 키 설정\n```bash\n# .env 파일 생성\necho \"GOV_API_KEY=your_api_key_here\" \u003e .env\n\n# 또는 환경변수로 설정\nexport GOV_API_KEY=your_api_key_here  # macOS/Linux\nset GOV_API_KEY=your_api_key_here     # Windows\n```\n\n#### .env 파일 예시\n```env\n# 국토교통부_(TAGO)_지하철정보 API 키\n# 공공데이터포털(https://www.data.go.kr/)에서 발급받은 API 키를 설정하세요\n# API URL: https://www.data.go.kr/data/15098554/openapi.do\nGOV_API_KEY=your_public_data_api_key_here\n\n# 예시:\n# GOV_API_KEY=abc123def456ghi789jkl012mno345pqr678stu901vwx234yz567\n```\n\n### 3. 개발 서버 실행\n```bash\nnpm run dev\n```\n\n### 4. 빌드\n```bash\nnpm run build\n```\n\n### 5. 테스트\n```bash\n# 전체 테스트\nnpm test\n\n# API 테스트\nnpm run test:api\n\n# 특정 역 테스트\nnpm run test:api:station\n```\n\n## 📡 API 연동\n\n### 국토교통부_(TAGO)_지하철정보 API\n- **API 명**: 국토교통부_(TAGO)_지하철정보\n- **API URL**: https://www.data.go.kr/data/15098554/openapi.do\n- **제공기관**: 국토교통부\n- **기본 URL**: `https://api.tago.go.kr`\n- **인증**: 공공데이터 API 키 기반 인증 (`GOV_API_KEY` 환경변수)\n- **데이터 형식**: JSON\n- **API 키 발급**: [공공데이터포털](https://www.data.go.kr/)에서 \"국토교통부_(TAGO)_지하철정보\" 신청\n\n### 환경변수 설정\n```bash\n# 필수 환경변수\nGOV_API_KEY=your_public_data_api_key_here\n```\n\n### 주요 엔드포인트\n- `GET /subway-station/search`: 지하철역 검색\n- `GET /subway-station/{stationCode}/timetable`: 열차 시간표 조회\n\n## 🎯 사용 예제\n\n### MCP 클라이언트 설정\nMCP 클라이언트에서 이 서버를 사용하려면 다음과 같이 설정하세요:\n\n```json\n{\n  \"mcpServers\": {\n    \"k-targo-subway\": {\n      \"command\": \"npx\",\n      \"args\": [\"k-targo-subway-mcp-server\"],\n      \"env\": {\n        \"GOV_API_KEY\": \"your_targo_api_key_here\"\n      }\n    }\n  }\n}\n```\n\n### MCP 클라이언트에서 사용\n```typescript\n// 지하철역 검색\nconst searchResult = await mcpClient.callTool('search_subway_station', {\n  stationName: '강남'\n});\n\n// 시간표 조회\nconst timetableResult = await mcpClient.callTool('get_station_timetable', {\n  stationCode: '0222',\n  direction: '상행'\n});\n```\n\n### CLI에서 직접 실행\n```bash\n# npx로 실행 (권장)\nnpx k-targo-subway-mcp-server\n\n# 글로벌 설치 후 실행\nk-targo-subway-mcp-server\n\n# 또는 npm 스크립트로 실행\nnpm start\n```\n\n## 🔄 개발 워크플로우\n\n1. **새 기능 추가**: `src/tools/`에 새 도구 파일 생성\n2. **API 연동**: `src/external/`에 외부 API 클라이언트 추가\n3. **타입 정의**: 필요한 타입들을 정의\n4. **테스트**: `test/` 디렉토리에 테스트 코드 작성\n5. **빌드 및 배포**: `npm run build` 후 배포\n\n## 📚 주요 개념\n\n### MCP Tool\n사용자가 호출할 수 있는 함수입니다. 입력 스키마와 핸들러 함수로 구성됩니다.\n\n### TAGO API\n국토교통부에서 제공하는 지하철 정보 API입니다. 공공데이터포털을 통해 제공됩니다.\n\n### 지하철역 코드\n각 지하철역은 고유한 코드를 가지고 있습니다 (예: 강남역 = \"0222\").\n\n## 🚀 배포\n\n```bash\n# 빌드\nnpm run build\n\n# npm 배포\nnpm publish\n\n# 실행\nnode dist/index.js\n```\n\n## 📄 라이선스\n\nMIT License\n\n## 🤝 기여하기\n\n1. Fork the Project\n2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the Branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n## 📞 문의\n\n- **GitHub**: [https://github.com/slicequeue/k-targo-subway-mcp-server](https://github.com/slicequeue/k-targo-subway-mcp-server)\n- **Issues**: [https://github.com/slicequeue/k-targo-subway-mcp-server/issues](https://github.com/slicequeue/k-targo-subway-mcp-server/issues)\n\n## 🙏 감사의 말\n\n- [국토교통부_(TAGO)_지하철정보](https://www.data.go.kr/data/15098554/openapi.do) - 지하철 정보 제공\n- [공공데이터포털](https://www.data.go.kr/) - API 서비스 제공\n- [Model Context Protocol](https://modelcontextprotocol.io) - MCP 표준\n- [Node.js](https://nodejs.org) - 런타임 환경 ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fslicequeue%2Fk-targo-subway-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fslicequeue%2Fk-targo-subway-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fslicequeue%2Fk-targo-subway-mcp-server/lists"}