# Directory Structure
```
├── .gitignore
├── Dockerfile
├── LICENSE
├── package-lock.json
├── package.json
├── README.md
├── smithery.yaml
├── src
│ ├── index.ts
│ └── tools
│ ├── addressSearchByPlaceName.ts
│ ├── directionSearchByAddress.ts
│ ├── directionSearchByCoordinates.ts
│ ├── futureDirectionSearchByCoordinates.ts
│ ├── geocode.ts
│ └── multiDestinationDirectionSearch.ts
└── tsconfig.json
```
# Files
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
```
# Dependencies
node_modules/
npm-debug.log*
yarn-debug.log*
yarn-error.log*
# Environment variables
.env
.env.local
.env.*.local
# Build output
dist/
build/
# IDE
.idea/
.vscode/
*.swp
*.swo
# OS
.DS_Store
Thumbs.db
```
--------------------------------------------------------------------------------
/smithery.yaml:
--------------------------------------------------------------------------------
```yaml
app:
name: kakao-mobility-mcp-server
version: 1.0.2
build:
type: docker
dockerfile: ./Dockerfile
deploy:
env:
- name: KAKAO_REST_API_KEY
required: true
port: 3000
health:
path: /health
port: 3000
resources:
memory: 512
cpu: 1
startCommand:
type: stdio
configSchema:
type: object
properties:
kakaoRestApiKey:
type: string
description: "Kakao REST API 키"
required:
- kakaoRestApiKey
commandFunction: |-
(config) => ({
"command": "node",
"args": [
"dist/index.js"
],
"env": {
"KAKAO_REST_API_KEY": config.kakaoRestApiKey
}
})
```
--------------------------------------------------------------------------------
/src/tools/geocode.ts:
--------------------------------------------------------------------------------
```typescript
import { z } from "zod";
import dotenv from "dotenv";
import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
dotenv.config();
export const geocodeSchema = {
placeName: z.string(),
};
export const geocodeHandler = async ({ placeName }: { placeName: string }): Promise<CallToolResult> => {
const response = await fetch(
`https://dapi.kakao.com/v2/local/search/address?query=${placeName}`,
{
method: "GET",
headers: {
"Content-Type": "application/json",
Authorization: `KakaoAK ${process.env.KAKAO_REST_API_KEY}`,
},
}
);
const data = await response.json();
return {
content: [{
type: "text",
text: JSON.stringify(data),
}],
isError: false,
};
};
```
--------------------------------------------------------------------------------
/src/tools/addressSearchByPlaceName.ts:
--------------------------------------------------------------------------------
```typescript
import { z } from "zod";
import dotenv from "dotenv";
import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
dotenv.config();
export const addressSearchByPlaceNameSchema = {
placeName: z.string(),
};
export const addressSearchByPlaceNameHandler = async ({ placeName }: { placeName: string }): Promise<CallToolResult> => {
const response = await fetch(
`https://dapi.kakao.com/v2/local/search/keyword?query=${placeName}`,
{
method: "GET",
headers: {
"Content-Type": "application/json",
Authorization: `KakaoAK ${process.env.KAKAO_REST_API_KEY}`,
},
}
);
const data = await response.json();
return {
content: [{
type: "text",
text: JSON.stringify(data),
}],
isError: false,
};
};
```
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
```json
{
"name": "traffic-data-mcp-server",
"version": "1.0.0",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1",
"build": "tsc",
"start": "node dist/index.js",
"inspect": "npx @modelcontextprotocol/inspector node dist/index.js"
},
"repository": {
"type": "git",
"url": "git+https://github.com/CaChiJ/traffic-data-mcp-server.git"
},
"author": "",
"license": "ISC",
"bugs": {
"url": "https://github.com/CaChiJ/traffic-data-mcp-server/issues"
},
"homepage": "https://github.com/CaChiJ/traffic-data-mcp-server#readme",
"description": "",
"dependencies": {
"@modelcontextprotocol/sdk": "^1.8.0",
"dotenv": "^16.4.7"
},
"devDependencies": {
"@types/node": "^22.14.0",
"typescript": "^5.8.3"
}
}
```
--------------------------------------------------------------------------------
/src/tools/directionSearchByCoordinates.ts:
--------------------------------------------------------------------------------
```typescript
import { z } from "zod";
import dotenv from "dotenv";
import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
dotenv.config();
export const directionSearchByCoordinatesSchema = {
originLongitude: z.number(),
originLatitude: z.number(),
destLongitude: z.number(),
destLatitude: z.number(),
};
export const directionSearchByCoordinatesHandler = async ({
originLongitude,
originLatitude,
destLongitude,
destLatitude,
}: {
originLongitude: number;
originLatitude: number;
destLongitude: number;
destLatitude: number;
}): Promise<CallToolResult> => {
const response = await fetch(
`https://apis-navi.kakaomobility.com/v1/directions?origin=${originLongitude},${originLatitude}&destination=${destLongitude},${destLatitude}`,
{
method: "GET",
headers: {
"Content-Type": "application/json",
Authorization: `KakaoAK ${process.env.KAKAO_REST_API_KEY}`,
},
}
);
const data = await response.json();
return {
content: [{
type: "text",
text: JSON.stringify(data),
}],
isError: false,
};
};
```
--------------------------------------------------------------------------------
/src/tools/futureDirectionSearchByCoordinates.ts:
--------------------------------------------------------------------------------
```typescript
import { z } from "zod";
import dotenv from "dotenv";
import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
dotenv.config();
export const futureDirectionSearchByCoordinatesSchema = {
originLatitude: z.number(),
originLongitude: z.number(),
destinationLatitude: z.number(),
destinationLongitude: z.number(),
departureTime: z.string(),
waypoints: z.string().optional(),
priority: z.enum(["RECOMMEND", "TIME", "DISTANCE"]).optional(),
avoid: z.string().optional(),
roadEvent: z.number().optional(),
alternatives: z.boolean().optional(),
roadDetails: z.boolean().optional(),
carType: z.number().optional(),
carFuel: z.enum(["GASOLINE", "DIESEL", "LPG"]).optional(),
carHipass: z.boolean().optional(),
summary: z.boolean().optional(),
};
export const futureDirectionSearchByCoordinatesHandler = async ({
originLatitude,
originLongitude,
destinationLatitude,
destinationLongitude,
departureTime,
waypoints,
priority,
avoid,
roadEvent,
alternatives,
roadDetails,
carType,
carFuel,
carHipass,
summary,
}: {
originLatitude: number;
originLongitude: number;
destinationLatitude: number;
destinationLongitude: number;
departureTime: string;
waypoints?: string;
priority?: string;
avoid?: string;
roadEvent?: number;
alternatives?: boolean;
roadDetails?: boolean;
carType?: number;
carFuel?: string;
carHipass?: boolean;
summary?: boolean;
}): Promise<CallToolResult> => {
let url = `https://apis-navi.kakaomobility.com/v1/future/directions?origin=${originLongitude},${originLatitude}&destination=${destinationLongitude},${destinationLatitude}&departure_time=${departureTime}`;
if (waypoints) url += `&waypoints=${waypoints}`;
if (priority) url += `&priority=${priority}`;
if (avoid) url += `&avoid=${avoid}`;
if (roadEvent !== undefined) url += `&roadevent=${roadEvent}`;
if (alternatives !== undefined) url += `&alternatives=${alternatives}`;
if (roadDetails !== undefined) url += `&road_details=${roadDetails}`;
if (carType !== undefined) url += `&car_type=${carType}`;
if (carFuel) url += `&car_fuel=${carFuel}`;
if (carHipass !== undefined) url += `&car_hipass=${carHipass}`;
if (summary !== undefined) url += `&summary=${summary}`;
const response = await fetch(url, {
method: "GET",
headers: {
"Content-Type": "application/json",
Authorization: `KakaoAK ${process.env.KAKAO_REST_API_KEY}`,
},
});
const data = await response.json();
return {
content: [{
type: "text",
text: JSON.stringify(data),
}],
isError: false,
};
};
```
--------------------------------------------------------------------------------
/src/tools/directionSearchByAddress.ts:
--------------------------------------------------------------------------------
```typescript
import { z } from "zod";
import dotenv from "dotenv";
import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
dotenv.config();
export const directionSearchByAddressSchema = {
originAddress: z.string(),
destAddress: z.string(),
};
export const directionSearchByAddressHandler = async ({
originAddress,
destAddress,
}: {
originAddress: string;
destAddress: string;
}): Promise<CallToolResult> => {
const [originResult, destResult]: [any, any] = await Promise.all([
(async () => {
const response = await fetch(
`https://dapi.kakao.com/v2/local/search/address?query=${originAddress}`,
{
method: "GET",
headers: {
"Content-Type": "application/json",
Authorization: `KakaoAK ${process.env.KAKAO_REST_API_KEY}`,
},
}
);
if (!response.ok) {
throw new Error(
`Kakao geocode API request failed for origin: ${response.statusText}`
);
}
const data = await response.json();
return data;
})(),
(async () => {
const response = await fetch(
`https://dapi.kakao.com/v2/local/search/address?query=${destAddress}`,
{
method: "GET",
headers: {
"Content-Type": "application/json",
Authorization: `KakaoAK ${process.env.KAKAO_REST_API_KEY}`,
},
}
);
if (!response.ok) {
throw new Error(
`Kakao geocode API request failed for destination: ${response.statusText}`
);
}
const data = await response.json();
return data;
})(),
]);
// Add basic error handling for geocoding results
if (
!originResult?.documents?.[0]?.x ||
!originResult?.documents?.[0]?.y ||
!destResult?.documents?.[0]?.x ||
!destResult?.documents?.[0]?.y
) {
// Consider returning a more informative error structure for MCP
return {
content: [{
type: "text",
text: "Geocoding failed or returned incomplete data for one or both locations.",
}],
isError: true,
};
}
const originLongitude = originResult.documents[0].x;
const originLatitude = originResult.documents[0].y;
const destLongitude = destResult.documents[0].x;
const destLatitude = destResult.documents[0].y;
const response = await fetch(
`https://apis-navi.kakaomobility.com/v1/directions?origin=${originLongitude},${originLatitude}&destination=${destLongitude},${destLatitude}`,
{
method: "GET",
headers: {
"Content-Type": "application/json",
Authorization: `KakaoAK ${process.env.KAKAO_REST_API_KEY}`,
},
}
);
const data = await response.json();
return {
content: [{
type: "text",
text: JSON.stringify(data),
}],
isError: false,
};
};
```
--------------------------------------------------------------------------------
/src/index.ts:
--------------------------------------------------------------------------------
```typescript
import {
McpServer,
ResourceTemplate,
} from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import dotenv from "dotenv";
dotenv.config();
import { directionSearchByCoordinatesSchema, directionSearchByCoordinatesHandler } from "./tools/directionSearchByCoordinates.js";
import { directionSearchByAddressSchema, directionSearchByAddressHandler } from "./tools/directionSearchByAddress.js";
import { addressSearchByPlaceNameSchema, addressSearchByPlaceNameHandler } from "./tools/addressSearchByPlaceName.js";
import { geocodeSchema, geocodeHandler } from "./tools/geocode.js";
import { futureDirectionSearchByCoordinatesSchema, futureDirectionSearchByCoordinatesHandler } from "./tools/futureDirectionSearchByCoordinates.js";
import { multiDestinationDirectionSearchSchema, multiDestinationDirectionSearchHandler } from "./tools/multiDestinationDirectionSearch.js";
// Create an MCP server
const server = new McpServer({
name: "Traffic Data MCP Server",
version: "1.0.2",
});
// Register tools
server.tool(
"direction_search_by_coords",
"Search for directions between two points using their coordinates (longitude and latitude). This tool provides navigation information including distance, duration, and route details.",
directionSearchByCoordinatesSchema,
directionSearchByCoordinatesHandler
);
server.tool(
"direction_search_by_address",
"Search for directions between two locations using their addresses. The tool first geocodes the addresses to coordinates, then finds the optimal route between them.",
directionSearchByAddressSchema,
directionSearchByAddressHandler
);
server.tool(
"address_search_by_place_name",
"Search for addresses using a place name or keyword. Returns detailed location information including coordinates and address details.",
addressSearchByPlaceNameSchema,
addressSearchByPlaceNameHandler
);
server.tool(
"geocode",
"Convert an address into geographic coordinates (geocoding). Returns the exact location coordinates and address details for the given place name.",
geocodeSchema,
geocodeHandler
);
server.tool(
"future_direction_search_by_coords",
"Search for directions with future departure time. Provides navigation information considering traffic predictions for a specific future time. Supports various options like waypoints, route preferences, and vehicle details.",
futureDirectionSearchByCoordinatesSchema,
futureDirectionSearchByCoordinatesHandler
);
server.tool(
"multi_destination_direction_search",
"Search for directions between a starting point and multiple destinations with coordinates. Returns a summary of the route including distance, duration, and route details. For detailed route information, additional calls to the car navigation API are required.",
multiDestinationDirectionSearchSchema,
multiDestinationDirectionSearchHandler
);
(async () => {
const transport = new StdioServerTransport();
await server.connect(transport);
})();
```
--------------------------------------------------------------------------------
/tsconfig.json:
--------------------------------------------------------------------------------
```json
{
"compilerOptions": {
/* Visit https://aka.ms/tsconfig to read more about this file */
/* Projects */
// "incremental": true, /* Save .tsbuildinfo files to allow for incremental compilation of projects. */
// "composite": true, /* Enable constraints that allow a TypeScript project to be used with project references. */
// "tsBuildInfoFile": "./.tsbuildinfo", /* Specify the path to .tsbuildinfo incremental compilation file. */
// "disableSourceOfProjectReferenceRedirect": true, /* Disable preferring source files instead of declaration files when referencing composite projects. */
// "disableSolutionSearching": true, /* Opt a project out of multi-project reference checking when editing. */
// "disableReferencedProjectLoad": true, /* Reduce the number of projects loaded automatically by TypeScript. */
/* Language and Environment */
"target": "es2017", /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */
// "lib": [], /* Specify a set of bundled library declaration files that describe the target runtime environment. */
// "jsx": "preserve", /* Specify what JSX code is generated. */
// "libReplacement": true, /* Enable lib replacement. */
// "experimentalDecorators": true, /* Enable experimental support for legacy experimental decorators. */
// "emitDecoratorMetadata": true, /* Emit design-type metadata for decorated declarations in source files. */
// "jsxFactory": "", /* Specify the JSX factory function used when targeting React JSX emit, e.g. 'React.createElement' or 'h'. */
// "jsxFragmentFactory": "", /* Specify the JSX Fragment reference used for fragments when targeting React JSX emit e.g. 'React.Fragment' or 'Fragment'. */
// "jsxImportSource": "", /* Specify module specifier used to import the JSX factory functions when using 'jsx: react-jsx*'. */
// "reactNamespace": "", /* Specify the object invoked for 'createElement'. This only applies when targeting 'react' JSX emit. */
// "noLib": true, /* Disable including any library files, including the default lib.d.ts. */
// "useDefineForClassFields": true, /* Emit ECMAScript-standard-compliant class fields. */
// "moduleDetection": "auto", /* Control what method is used to detect module-format JS files. */
/* Modules */
"module": "nodenext", /* Specify what module code is generated. */
// "rootDir": "./", /* Specify the root folder within your source files. */
"moduleResolution": "nodenext", /* Specify how TypeScript looks up a file from a given module specifier. */
// "baseUrl": "./", /* Specify the base directory to resolve non-relative module names. */
// "paths": {}, /* Specify a set of entries that re-map imports to additional lookup locations. */
// "rootDirs": [], /* Allow multiple folders to be treated as one when resolving modules. */
// "typeRoots": [], /* Specify multiple folders that act like './node_modules/@types'. */
// "types": [], /* Specify type package names to be included without being referenced in a source file. */
// "allowUmdGlobalAccess": true, /* Allow accessing UMD globals from modules. */
// "moduleSuffixes": [], /* List of file name suffixes to search when resolving a module. */
// "allowImportingTsExtensions": true, /* Allow imports to include TypeScript file extensions. Requires '--moduleResolution bundler' and either '--noEmit' or '--emitDeclarationOnly' to be set. */
// "rewriteRelativeImportExtensions": true, /* Rewrite '.ts', '.tsx', '.mts', and '.cts' file extensions in relative import paths to their JavaScript equivalent in output files. */
// "resolvePackageJsonExports": true, /* Use the package.json 'exports' field when resolving package imports. */
// "resolvePackageJsonImports": true, /* Use the package.json 'imports' field when resolving imports. */
// "customConditions": [], /* Conditions to set in addition to the resolver-specific defaults when resolving imports. */
// "noUncheckedSideEffectImports": true, /* Check side effect imports. */
// "resolveJsonModule": true, /* Enable importing .json files. */
// "allowArbitraryExtensions": true, /* Enable importing files with any extension, provided a declaration file is present. */
// "noResolve": true, /* Disallow 'import's, 'require's or '<reference>'s from expanding the number of files TypeScript should add to a project. */
/* JavaScript Support */
// "allowJs": true, /* Allow JavaScript files to be a part of your program. Use the 'checkJS' option to get errors from these files. */
// "checkJs": true, /* Enable error reporting in type-checked JavaScript files. */
// "maxNodeModuleJsDepth": 1, /* Specify the maximum folder depth used for checking JavaScript files from 'node_modules'. Only applicable with 'allowJs'. */
/* Emit */
// "declaration": true, /* Generate .d.ts files from TypeScript and JavaScript files in your project. */
// "declarationMap": true, /* Create sourcemaps for d.ts files. */
// "emitDeclarationOnly": true, /* Only output d.ts files and not JavaScript files. */
// "sourceMap": true, /* Create source map files for emitted JavaScript files. */
// "inlineSourceMap": true, /* Include sourcemap files inside the emitted JavaScript. */
// "noEmit": true, /* Disable emitting files from a compilation. */
// "outFile": "./", /* Specify a file that bundles all outputs into one JavaScript file. If 'declaration' is true, also designates a file that bundles all .d.ts output. */
"outDir": "./dist", /* Specify an output folder for all emitted files. */
// "removeComments": true, /* Disable emitting comments. */
// "importHelpers": true, /* Allow importing helper functions from tslib once per project, instead of including them per-file. */
// "downlevelIteration": true, /* Emit more compliant, but verbose and less performant JavaScript for iteration. */
// "sourceRoot": "", /* Specify the root path for debuggers to find the reference source code. */
// "mapRoot": "", /* Specify the location where debugger should locate map files instead of generated locations. */
// "inlineSources": true, /* Include source code in the sourcemaps inside the emitted JavaScript. */
// "emitBOM": true, /* Emit a UTF-8 Byte Order Mark (BOM) in the beginning of output files. */
// "newLine": "crlf", /* Set the newline character for emitting files. */
// "stripInternal": true, /* Disable emitting declarations that have '@internal' in their JSDoc comments. */
// "noEmitHelpers": true, /* Disable generating custom helper functions like '__extends' in compiled output. */
// "noEmitOnError": true, /* Disable emitting files if any type checking errors are reported. */
// "preserveConstEnums": true, /* Disable erasing 'const enum' declarations in generated code. */
// "declarationDir": "./", /* Specify the output directory for generated declaration files. */
/* Interop Constraints */
// "isolatedModules": true, /* Ensure that each file can be safely transpiled without relying on other imports. */
// "verbatimModuleSyntax": true, /* Do not transform or elide any imports or exports not marked as type-only, ensuring they are written in the output file's format based on the 'module' setting. */
// "isolatedDeclarations": true, /* Require sufficient annotation on exports so other tools can trivially generate declaration files. */
// "erasableSyntaxOnly": true, /* Do not allow runtime constructs that are not part of ECMAScript. */
// "allowSyntheticDefaultImports": true, /* Allow 'import x from y' when a module doesn't have a default export. */
"esModuleInterop": true, /* Emit additional JavaScript to ease support for importing CommonJS modules. This enables 'allowSyntheticDefaultImports' for type compatibility. */
// "preserveSymlinks": true, /* Disable resolving symlinks to their realpath. This correlates to the same flag in node. */
"forceConsistentCasingInFileNames": true, /* Ensure that casing is correct in imports. */
/* Type Checking */
"strict": true, /* Enable all strict type-checking options. */
// "noImplicitAny": true, /* Enable error reporting for expressions and declarations with an implied 'any' type. */
// "strictNullChecks": true, /* When type checking, take into account 'null' and 'undefined'. */
// "strictFunctionTypes": true, /* When assigning functions, check to ensure parameters and the return values are subtype-compatible. */
// "strictBindCallApply": true, /* Check that the arguments for 'bind', 'call', and 'apply' methods match the original function. */
// "strictPropertyInitialization": true, /* Check for class properties that are declared but not set in the constructor. */
// "strictBuiltinIteratorReturn": true, /* Built-in iterators are instantiated with a 'TReturn' type of 'undefined' instead of 'any'. */
// "noImplicitThis": true, /* Enable error reporting when 'this' is given the type 'any'. */
// "useUnknownInCatchVariables": true, /* Default catch clause variables as 'unknown' instead of 'any'. */
// "alwaysStrict": true, /* Ensure 'use strict' is always emitted. */
// "noUnusedLocals": true, /* Enable error reporting when local variables aren't read. */
// "noUnusedParameters": true, /* Raise an error when a function parameter isn't read. */
// "exactOptionalPropertyTypes": true, /* Interpret optional property types as written, rather than adding 'undefined'. */
// "noImplicitReturns": true, /* Enable error reporting for codepaths that do not explicitly return in a function. */
// "noFallthroughCasesInSwitch": true, /* Enable error reporting for fallthrough cases in switch statements. */
// "noUncheckedIndexedAccess": true, /* Add 'undefined' to a type when accessed using an index. */
// "noImplicitOverride": true, /* Ensure overriding members in derived classes are marked with an override modifier. */
// "noPropertyAccessFromIndexSignature": true, /* Enforces using indexed accessors for keys declared using an indexed type. */
// "allowUnusedLabels": true, /* Disable error reporting for unused labels. */
// "allowUnreachableCode": true, /* Disable error reporting for unreachable code. */
/* Completeness */
// "skipDefaultLibCheck": true, /* Skip type checking .d.ts files that are included with TypeScript. */
"skipLibCheck": true /* Skip type checking all .d.ts files. */
}
}
```