# occ-gis-mcp

An MCP (Model Context Protocol) server that gives AI assistants (like Claude, GitHub
Copilot, or any MCP-compatible client) access to public GIS datasets from the
Oklahoma Corporation Commission's open data hub:
https://gisdata-occokc.opendata.arcgis.com/

**No coding experience required to set this up.** Follow the steps below in order.

## What is this, in plain terms?

MCP ("Model Context Protocol") is a standard way for AI chat tools to call small
programs ("servers") that fetch live data. This repo *is* one of those servers.
Once it's set up, you can ask your AI assistant things like:

- "List the datasets available from the OCC GIS hub"
- "Find all active oil wells in Oklahoma County"
- "Show me the fields available on the PST Tanks layer"

and the assistant will use this server to fetch real, live answers instead of guessing.

## Step 1 — Install Node.js

This server runs on Node.js. If you don't already have it:

1. Go to https://nodejs.org
2. Download the **LTS** (Long Term Support) version for your operating system.
3. Run the installer, accepting the defaults.
4. Confirm it worked by opening a terminal (PowerShell on Windows, Terminal on
   Mac/Linux) and running:
   ```
   node -v
   npm -v
   ```
   Both should print a version number (e.g. `v20.11.0`). If you see an error,
   restart your terminal/computer and try again.

## Step 2 — Download this project

**Option A: Using Git (recommended if you have it)**
```
git clone https://github.com/MSPFE2019/occ-gis-mcp.git
cd occ-gis-mcp
```

**Option B: Without Git**
1. Go to https://github.com/MSPFE2019/occ-gis-mcp
2. Click the green **Code** button → **Download ZIP**
3. Unzip it somewhere you'll remember (e.g. your Documents folder)
4. Open a terminal and `cd` into that unzipped folder, for example:
   ```
   cd "C:\Users\YourName\Documents\occ-gis-mcp"
   ```

## Step 3 — Install dependencies

From inside the project folder, run:
```
npm install
```
This downloads the small libraries the server needs. You only need to do this once
(and again any time the code changes).

## Step 4 — Test that it runs

There are two ways to run this server — pick based on where you'll use it:

- **`index.js`** — for local desktop tools (Claude Desktop, VS Code/Copilot Chat).
- **`http.js`** — for remote/cloud tools like **Copilot Studio** (see the
  dedicated section below).

Try the local one first:
```
node index.js
```
Nothing will print — that's expected! MCP servers talk over a silent input/output
channel and just wait for a client to connect. Press `Ctrl+C` to stop it.

For a more visual test, use the official MCP Inspector, which opens a browser page
where you can click buttons and see live results:
```
npx @modelcontextprotocol/inspector node index.js
```
This opens a local webpage. Click **Connect**, then **List Tools**, then try running
`list_datasets` with no arguments — you should see a list of real datasets come back
as JSON. If that works, the server is working correctly.

## Step 5 — Connect it to your AI assistant

MCP servers are configured once inside your AI client's settings. Pick the guide
that matches your tool:

### Claude Desktop
1. Open Claude Desktop → Settings → Developer → **Edit Config** (this opens
   `claude_desktop_config.json` in a text editor).
2. Add an entry like this (replace the path with your actual project folder,
   using double backslashes `\\` on Windows):
   ```json
   {
     "mcpServers": {
       "occ-gis": {
         "command": "node",
         "args": ["C:\\Users\\YourName\\Documents\\occ-gis-mcp\\index.js"]
       }
     }
   }
   ```
3. Save the file and fully restart Claude Desktop.
4. Ask it: "What OCC GIS datasets are available?"

### VS Code (GitHub Copilot Chat) or other MCP-aware editors
1. Open (or create) an `mcp.json` file in your MCP settings (in VS Code:
   Command Palette → "MCP: Open User Configuration", or add it to your workspace's
   `.vscode/mcp.json`).
2. Add the same `mcpServers` block shown above.
3. Reload the window and the new tools will appear when you chat with Copilot.

### Any other MCP client
Any client that supports the MCP standard accepts the same shape of config:
a `command` (`node`) and `args` (the full path to `index.js`). Consult your
client's documentation for where that config file lives.

## Available tools

Once connected, your assistant can call these:

| Tool | What it does |
|---|---|
| `list_datasets` | Search/list the datasets on the hub (wells, tanks, etc.). Optional free-text `query`. |
| `get_dataset` | Full details for one dataset by title, including download links (CSV, GeoJSON, Shapefile, KML, File Geodatabase) and its live ArcGIS service URL. |
| `get_layer_metadata` | Field names, geometry type, and extent for a given ArcGIS layer URL. |
| `query_layer` | Run attribute (`where`) and/or spatial queries against a layer and get back matching records. |

## Customizing for a different ArcGIS Hub site

This server isn't limited to the OCC's data — it works with any ArcGIS Hub site
that exposes a DCAT-US catalog feed (most public ArcGIS Hub sites do). To point it
at a different site, open `server.js` and change this line near the top:
```js
const HUB_BASE = "https://gisdata-occokc.opendata.arcgis.com";
```
to your target site's base URL, then re-run the server. Everything else
(tool names, query logic) works the same way.

## Connecting to Microsoft Copilot Studio

Copilot Studio doesn't run this server for you — it needs to reach it over the
internet as an HTTPS URL. That's what `http.js` is for (as opposed to `index.js`,
which is only for local tools like Claude Desktop). There are two parts:
**(A)** put the server somewhere reachable on the internet, then **(B)** register
it in Copilot Studio.

### A. Deploy the HTTP server somewhere public

Pick whichever is easiest for you — all of them run the same command:
`npm install` then `npm run start:http`.

**Easiest for beginners — Azure App Service (or Azure Container Apps)**
1. Push this repo to your own GitHub account (already done if you're reading this
   from your fork/copy).
2. In the Azure Portal, create a **Web App** → Runtime stack: **Node 20 LTS** →
   deploy from your GitHub repo (Azure sets up CI/CD for you).
3. Under **Configuration → Startup Command**, set:
   ```
   node http.js
   ```
4. Once deployed, Azure gives you a URL like `https://occ-gis-mcp.azurewebsites.net`.
   Your MCP endpoint is that URL plus `/mcp`, e.g.
   `https://occ-gis-mcp.azurewebsites.net/mcp`.

**Also simple — Render, Railway, or Fly.io**
Any of these can deploy a Node.js repo from GitHub in a few clicks:
- Build command: `npm install`
- Start command: `npm run start:http`
- They'll give you a public `https://...` URL — again, append `/mcp`.

**Local testing only (not for production)**
```
npm install
npm run start:http
```
This starts the server at `http://localhost:3000/mcp`. To test whether Copilot
Studio (a cloud service) can reach a server on your own machine, you'd need a
tunnel tool like `ngrok` (`ngrok http 3000`), which gives you a temporary public
HTTPS URL. This is fine for a quick demo, not for real/ongoing use.

### B. Register it in Copilot Studio

1. Open your agent in **Copilot Studio** → go to **Tools** (or **Actions**) →
   **Add a tool** → **New tool** → **Model Context Protocol**.
2. Give it a name (e.g. "OCC GIS Data") and paste your server's HTTPS URL
   **including `/mcp`**, e.g. `https://occ-gis-mcp.azurewebsites.net/mcp`.
3. Choose **No authentication** (this server is read-only and doesn't require
   credentials) unless you've added your own auth layer in front of it.
4. Save. Copilot Studio will call the server and automatically discover the four
   tools (`list_datasets`, `get_dataset`, `get_layer_metadata`, `query_layer`)
   along with their descriptions — no manual schema entry needed.
5. Test it in the Copilot Studio test chat pane: ask "What OCC GIS datasets are
   available?" or "Find active wells in Oklahoma County."

## Available tools

Once connected, your assistant can call these:

| Tool | What it does |
|---|---|
| `list_datasets` | Search/list the datasets on the hub (wells, tanks, etc.). Optional free-text `query`. |
| `get_dataset` | Full details for one dataset by title, including download links (CSV, GeoJSON, Shapefile, KML, File Geodatabase) and its live ArcGIS service URL. |
| `get_layer_metadata` | Field names, geometry type, and extent for a given ArcGIS layer URL. |
| `query_layer` | Run attribute (`where`) and/or spatial queries against a layer and get back matching records. |

## Troubleshooting

- **`node: command not found`** — Node.js isn't installed or your terminal needs
  restarting after installation. Redo Step 1.
- **Inspector/tool call errors mentioning network/fetch** — check your internet
  connection; the server calls the live ArcGIS Hub API on every request.
- **Assistant doesn't see the new tools** — double check the file path (local) or
  URL (Copilot Studio) is correct, and that you fully restarted/reconnected the
  client.
- **Copilot Studio says it can't connect** — make sure you registered the URL
  ending in `/mcp` (not just the bare domain), that the deployment is actually
  running, and that it's reachable over plain HTTPS (no VPN/firewall blocking it).

## Notes

- The dataset list is pulled live from the hub's DCAT-US catalog feed and cached
  for 15 minutes to keep things fast.
- Data is public but subject to the source agency's terms of use (shown in the
  `get_dataset` output's license field).
- `http.js` runs in stateless mode (a fresh server per request), which keeps
  hosting simple and is fully compatible with how Copilot Studio calls MCP tools.