TypeScript MCP Server Boilerplate

Instructions

Implementation Reference

• src/index.ts:160-271 (handler)

  The 'geocode' tool is registered using 'server.registerTool' in src/index.ts, with its input/output schemas and execution logic (handler) directly defined within the call. The handler makes a request to the Nominatim OpenStreetMap API.

  server.registerTool(
      'geocode',
      {
          description:
              '도시 이름이나 주소를 입력받아 위도·경도 좌표를 반환합니다. (Nominatim OpenStreetMap API 사용)',
          inputSchema: z.object({
              query: z.string().describe('도시 이름 또는 주소'),
              limit: z
                  .number()
                  .int()
                  .min(1)
                  .max(10)
                  .optional()
                  .default(5)
                  .describe('최대 결과 수 (기본값: 5, 최대: 10)'),
              countrycodes: z
                  .string()
                  .optional()
                  .describe('국가 코드 필터 (ISO 3166-1 alpha-2, 예: "kr,us")')
          }),
          outputSchema: z.object({
              content: z.array(
                  z.object({
                      type: z.literal('text'),
                      text: z.string().describe('검색 결과 요약 메시지')
                  })
              ),
              results: z.array(
                  z.object({
                      displayName: z.string().describe('전체 주소 문자열'),
                      lat: z.number().describe('위도'),
                      lon: z.number().describe('경도'),
                      type: z.string().describe('장소 유형'),
                      importance: z.number().describe('관련도 점수')
                  })
              )
          })
      },
      async ({ query, limit, countrycodes }) => {
          const params = new URLSearchParams({
              q: query,
              format: 'json',
              addressdetails: '1',
              limit: String(limit)
          })
          if (countrycodes) {
              params.set('countrycodes', countrycodes)
          }
  
          const response = await fetch(
              `https://nominatim.openstreetmap.org/search?${params}`,
              {
                  headers: {
                      'User-Agent': 'typescript-mcp-server/1.0',
                      'Accept-Language': 'ko,en'
                  }
              }
          )
  
          if (!response.ok) {
              throw new Error(
                  `Nominatim API 오류: ${response.status} ${response.statusText}`
              )
          }
  
          const data = (await response.json()) as Array<{
              lat: string
              lon: string
              display_name: string
              type: string
              importance: number
          }>
  
          if (data.length === 0) {
              throw new Error(`"${query}"에 대한 검색 결과가 없습니다.`)
          }
  
          const results = data.map((item) => ({
              displayName: item.display_name,
              lat: parseFloat(item.lat),
              lon: parseFloat(item.lon),
              type: item.type,
              importance: item.importance
          }))
  
          const summary = results
              .map(
                  (r, i) =>
                      `${i + 1}. ${r.displayName}\n   위도: ${r.lat}, 경도: ${r.lon}`
              )
              .join('\n')
          const message = `"${query}" 검색 결과 ${results.length}건:\n${summary}`
  
          return {
              content: [
                  {
                      type: 'text' as const,
                      text: message
                  }
              ],
              structuredContent: {
                  content: [
                      {
                          type: 'text' as const,
                          text: message
                      }
                  ],
                  results
              }
          }
      }
  )