feat(server): init Geocoding MCP server

.github/workflows/lint.yml

@@ -0,0 +1,23 @@
+name: Lint
+
+on:
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v1
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install
+
+      - name: Run Lint
+        run: bun run lint

.github/workflows/release.yml

@@ -0,0 +1,50 @@
+name: Release
+
+on:
+  release:
+    types:
+      - published
+
+jobs:
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@v4
+
+      - name: Set env
+        run: echo "VERSION=${GITHUB_REF#refs/*/}" >> $GITHUB_ENV
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v1
+        with:
+          bun-version: latest
+
+      - name: Set package version
+        run: |
+          echo $(jq --arg v "${{ env.VERSION }}" '(.version) = $v' package.json) > package.json
+
+      - name: Update version in source file
+        run: |
+          sed -i "s/version: \"[0-9]*\.[0-9]*\.[0-9]*\"/version: \"${{ env.VERSION }}\"/" src/index.ts
+
+      - name: Install Dependencies
+        run: bun install
+
+      - name: Build
+        run: bun run build
+
+      - name: Publish
+        if: ${{ !github.event.release.prerelease }}
+        env:
+          NPM_CONFIG_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          bun publish
+
+      - name: Publish release candidate
+        if: ${{ github.event.release.prerelease }}
+        env:
+          NPM_CONFIG_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          bun publish --tag=canary

.gitignore

@@ -0,0 +1,37 @@
+# dependencies (bun install)
+node_modules
+
+# output
+out
+dist
+*.tgz
+
+# code coverage
+coverage
+*.lcov
+
+# logs
+logs
+*.log
+report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
+
+# dotenv environment variable files
+.env
+.env.development.local
+.env.test.local
+.env.production.local
+.env.local
+
+# caches
+.eslintcache
+.cache
+*.tsbuildinfo
+
+# IntelliJ based IDEs
+.idea
+
+# Finder (MacOS) folder config
+.DS_Store
+
+# Trae
+.trae

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Geocoding AI
+Copyright (c) 2025 Srihari Thalla
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -0,0 +1,34 @@
+![CodeRabbit Pull Request Reviews](https://img.shields.io/coderabbit/prs/github/geocoding-ai/mcp?utm_source=oss&utm_medium=github&utm_campaign=geocoding-ai%2Fmcp&labelColor=171717&color=FF570A&link=https%3A%2F%2Fcoderabbit.ai&label=CodeRabbit+Reviews)
+
+# Geocoding MCP Server
+
+This is a Model Context Protocol (MCP) server that provides geocoding services by integrating with the Nominatim API.
+
+## Installation
+
+### Requirements
+- Node.js >= 18.0.0
+- Cursor, Windsurf, Claude Desktop, Trae or another MCP Client
+
+## Install in Claude Desktop
+Add this to your Claude Desktop `claude_desktop_config.json` file. See [Claude Desktop MCP docs](https://modelcontextprotocol.io/quickstart/user) for more info.
+
+```json
+{
+  "mcpServers": {
+    "geocoding": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@geocoding-ai/mcp"
+      ]
+    }
+  }
+}
+```
+
+## License
+
+Codebase: [MIT](./LICENSE)
+
+Documentation: [GPLv2](https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html) / [Nominatim developer community](https://github.com/osm-search/Nominatim) / [Nominatim Manual](https://nominatim.org/release-docs/latest/)

eslint.config.js

@@ -0,0 +1,19 @@
+// @ts-check
+
+import eslint from '@eslint/js'
+import tseslint from 'typescript-eslint'
+
+export default tseslint.config(
+  {
+    extends: [
+      eslint.configs.recommended,
+      tseslint.configs.recommended,
+    ],
+    rules: {
+      'semi': ['error', 'never'],
+      '@typescript-eslint/no-explicit-any': 'off',
+      '@typescript-eslint/no-unused-vars': 'off',
+      'comma-dangle': ['error', 'always-multiline'],
+    },
+  },
+)

package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@geocoding-ai/mcp",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "type": "module",
+  "version": "0.1.0",
+  "files": [
+    "dist"
+  ],
+  "private": false,
+  "publishConfig": {
+    "access": "public",
+    "tag": "latest"
+  },
+  "scripts": {
+    "build": "tsc",
+    "inspect": "bunx @modelcontextprotocol/inspector node dist/index.js",
+    "watch": "tsc --watch",
+    "lint": "eslint src"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.28.0",
+    "@types/bun": "latest",
+    "eslint": "^9.28.0",
+    "typescript-eslint": "^8.33.0"
+  },
+  "peerDependencies": {
+    "typescript": "^5.8.3"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "axios": "^1.9.0"
+  }
+}

src/clients/nominatimClient.ts

@@ -0,0 +1,22 @@
+import axios from 'axios'
+import type { ReverseGeocodeParams } from '../types/reverseGeocodeTypes.js'
+import type { GeocodeParams } from '../types/geocodeTypes.js'
+
+const nominatimClient = axios.create({
+  baseURL: 'https://nominatim.geocoding.ai/',
+  headers: {
+    'User-Agent': 'GeocodingMCP/1.0',
+  },
+})
+
+const condenseOutput = (result: any[]) => result.map(({ licence, ...item }) => item)
+
+export const geocodeAddress = async (params: GeocodeParams) => {
+  const response = await nominatimClient.get('search', { params })
+  return condenseOutput(response.data)
+}
+
+export const reverseGeocode = async (params: ReverseGeocodeParams) => {
+  const response = await nominatimClient.get('reverse', { params })
+  return condenseOutput([response.data])
+}

src/index.ts

@@ -0,0 +1,24 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
+import { registerGeocodeTool } from "./tools/geocode.js"
+import { registerReverseGeocodeTool } from "./tools/reverseGeocode.js"
+
+const server = new McpServer({
+  name: "geocoding",
+  version: "0.1.0",
+  description: "Geocoding API",
+})
+
+registerGeocodeTool(server)
+registerReverseGeocodeTool(server)
+
+async function main() {
+  const transport = new StdioServerTransport()
+  await server.connect(transport)
+  console.error("Geocoding API MCP Server running on stdio")
+}
+
+main().catch((error) => {
+  console.error("Fatal error in main():", error)
+  process.exit(1)
+})

src/tools/geocode.ts

@@ -0,0 +1,51 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"
+import { geocodeAddress } from "../clients/nominatimClient.js"
+import { handleGeocodeResult } from "./prepareResponse.js"
+import { GeocodeParamsSchema, type GeocodeParams } from "../types/geocodeTypes.js"
+
+export const registerGeocodeTool = (server: McpServer) => {
+  server.tool(
+    "geocode",
+    `Geocoding generates a coordinate from an address.
+
+The search API allows to look up a location from a textual description or address. Nominatim supports structured and free-form search queries.
+The search query may also contain special phrases which are translated into specific OpenStreetMap (OSM) tags (e.g. Pub => amenity=pub). This can be used to narrow down the kind of objects to be returned.
+    Note: Special phrases are not suitable to query all objects of a certain type in an area. Nominatim will always just return a collection of the best matches.
+
+Input:
+- query: Free-form string to search for. In this form, the query can be unstructured. Free-form queries are processed first left-to-right and then right-to-left if that fails.
+        Commas are optional, but improve performance by reducing the complexity of the search. The free-form may also contain special phrases to describe the type of place to be returned or a coordinate to search close to a position.
+- format: Format of the response. One of: xml, json, jsonv2, geojson, geocodejson. Default: jsonv2
+- addressdetails: When set to 1, include a breakdown of the address into elements. The exact content of the address breakdown depends on the output format.
+- extratags: When set to 1, the response include any additional information in the result that is available in the Nominatim database.
+- namedetails: When set to 1, include a full list of names for the result. These may include language variants, older names, references and brand.
+- countrycodes: Filter that limits the search results to one or more countries. The country code must be the ISO 3166-1alpha2 code of the country.
+                Each place in Nominatim is assigned to one country code based on OSM country boundaries. In rare cases a place may not be in any country at all, for example, when it is in international waters. These places are also excluded when the filter is set.
+- layer: The layer filter allows to select places by themes. Comma-separated list of: address, poi, railway, natural, manmade
+        address:  The address layer contains all places that make up an address: address points with house numbers, streets, inhabited places (suburbs, villages, cities, states etc.) and administrative boundaries.
+        poi:      The poi layer selects all point of interest. This includes classic points of interest like restaurants, shops, hotels but also less obvious features like recycling bins, guideposts or benches.
+        railway:  The railway layer includes railway infrastructure like tracks. Note that in Nominatim's standard configuration, only very few railway features are imported into the database.
+        natural:  The natural layer collects features like rivers, lakes and mountains while the manmade layer functions as a catch-all for features not covered by the other layers.
+        manmade:  The manmade layer collects features that are man-made.
+- featureType: Allows to have a more fine-grained selection for places from the address layer. Results can be restricted to places that make up the 'state', 'country' or 'city' part of an address. A featureType of settlement selects any human inhabited feature from 'state' down to 'neighbourhood'.
+              When featureType is set, then results are automatically restricted to the address layer.
+- polygon_geojson: Add the full geometry of the place to the result output. Output formats in GeoJSON, KML, SVG or WKT are supported. Only one of these options can be used at a time.
+- polygon_kml: Add the full geometry of the place to the result output. Output formats in GeoJSON, KML, SVG or WKT are supported. Only one of these options can be used at a time.
+- polygon_svg: Add the full geometry of the place to the result output. Output formats in GeoJSON, KML, SVG or WKT are supported. Only one of these options can be used at a time.
+- polygon_text: Add the full geometry of the place to the result output. Output formats in GeoJSON, KML, SVG or WKT are supported. Only one of these options can be used at a time.
+- polygon_threshold: When one of the polygon_* outputs is chosen, return a simplified version of the output geometry. The parameter describes the tolerance in degrees with which the geometry may differ from the original geometry. Topology is preserved in the geometry.
+
+Output:
+See https://nominatim.org/release-docs/latest/api/Output/ for the output format.
+
+License:
+Data © OpenStreetMap contributors, ODbL 1.0. http://osm.org/copyright
+`,
+    GeocodeParamsSchema,
+    async (params: GeocodeParams) => {
+      const result = await geocodeAddress(params)
+
+      return handleGeocodeResult(result)
+    },
+  )
+}

src/tools/prepareResponse.ts

@@ -0,0 +1,22 @@
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js"
+
+export const handleGeocodeResult = (result: any): CallToolResult => {
+  let text = ""
+
+  if (!result || !Array.isArray(result) || result.length === 0) {
+    text = "This service is unable to find an address for the given query."
+  } else {
+    try {
+      text = JSON.stringify(result)
+    } catch (error) {
+      text = `This service is unable to format the response as JSON. Error serializing geocode result: ${error instanceof Error ? error.message : String(error)}`
+    }
+  }
+
+  return {
+    content: [{
+      type: "text",
+      text,
+    }],
+  }
+}

src/tools/reverseGeocode.ts

@@ -0,0 +1,60 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"
+import { reverseGeocode } from "../clients/nominatimClient.js"
+import { handleGeocodeResult } from "./prepareResponse.js"
+import { ReverseGeocodeParamsSchema, type ReverseGeocodeParams } from "../types/reverseGeocodeTypes.js"
+
+export const registerReverseGeocodeTool = (server: McpServer) => {
+  server.tool(
+    "reverse_geocode",
+    `Reverse geocoding generates an address from a coordinate given as latitude and longitude.
+
+This tool finds the closest suitable OpenStreetMap (OSM) object and returns its address information.
+The tool uses the Nominatim API to perform the reverse geocoding and returns the address information in a JSON object.
+
+Input:
+- lat: Latitude of the coordinate in WGS84 projection.
+- lon: Longitude of the coordinate in WGS84 projection.
+- zoom: Level of detail required for the address.
+        This is a number that corresponds roughly to the zoom level used in XYZ tile sources in frameworks like Leaflet.js, Openlayers etc.
+        In terms of address details the zoom levels are as follows:
+        3:	country
+        5:	state
+        8:	county
+        10:	city
+        12:	town / borough
+        13:	village / suburb
+        14:	neighbourhood
+        15:	any settlement
+        16:	major streets
+        17:	major and minor streets
+        18:	buildings
+- format: Format of the response. One of: xml, json, jsonv2, geojson, geocodejson. Default: jsonv2
+- addressdetails: When set to 1, include a breakdown of the address into elements. The exact content of the address breakdown depends on the output format.
+- extratags: When set to 1, the response include any additional information in the result that is available in the Nominatim database.
+- namedetails: When set to 1, include a full list of names for the result. These may include language variants, older names, references and brand.
+- layer: The layer filter allows to select places by themes. Comma-separated list of: address, poi, railway, natural, manmade
+        address:  The address layer contains all places that make up an address: address points with house numbers, streets, inhabited places (suburbs, villages, cities, states etc.) and administrative boundaries.
+        poi:      The poi layer selects all point of interest. This includes classic points of interest like restaurants, shops, hotels but also less obvious features like recycling bins, guideposts or benches.
+        railway:  The railway layer includes railway infrastructure like tracks. Note that in Nominatim's standard configuration, only very few railway features are imported into the database.
+        natural:  The natural layer collects features like rivers, lakes and mountains while the manmade layer functions as a catch-all for features not covered by the other layers.
+        manmade:  The manmade layer collects features that are man-made.
+- polygon_geojson: Add the full geometry of the place to the result output. Output formats in GeoJSON, KML, SVG or WKT are supported. Only one of these options can be used at a time.
+- polygon_kml: Add the full geometry of the place to the result output. Output formats in GeoJSON, KML, SVG or WKT are supported. Only one of these options can be used at a time.
+- polygon_svg: Add the full geometry of the place to the result output. Output formats in GeoJSON, KML, SVG or WKT are supported. Only one of these options can be used at a time.
+- polygon_text: Add the full geometry of the place to the result output. Output formats in GeoJSON, KML, SVG or WKT are supported. Only one of these options can be used at a time.
+- polygon_threshold: When one of the polygon_* outputs is chosen, return a simplified version of the output geometry. The parameter describes the tolerance in degrees with which the geometry may differ from the original geometry. Topology is preserved in the geometry.
+
+Output:
+See https://nominatim.org/release-docs/latest/api/Output/ for the output format.
+
+License:
+Data © OpenStreetMap contributors, ODbL 1.0. http://osm.org/copyright
+`,
+    ReverseGeocodeParamsSchema,
+    async (params: ReverseGeocodeParams) => {
+      const result = await reverseGeocode(params)
+
+      return handleGeocodeResult(result)
+    },
+  )
+}