[DO NOT MERGE] - POC of MMGIS Agent Design

.gitignore

@@ -31,6 +31,7 @@ nul
 # Wildcard patterns for component plugins
 /src/essence/*Private-Components*
 /src/essence/*Plugin-Components*
+!/src/essence/MMGIS-Plugin-Components/
 
 /src/pre/tools.js
 /src/pre/components.js
@@ -54,8 +55,6 @@ sessions
 .terraform/
 .terraform.lock.hcl
 
-
-.mcp.json
 .serena
 .claude/*
 !.claude/skills/

.mcp.json

@@ -0,0 +1,12 @@
+{
+    "mcpServers": {
+        "mmgis": {
+            "command": "node",
+            "args": ["mcp/dist/index.js"],
+            "env": {
+                "MMGIS_URL": "http://localhost:8888",
+                "MMGIS_TOKEN": "${MMGIS_TOKEN}"
+            }
+        }
+    }
+}

AGENTS.md

@@ -132,6 +132,8 @@ MMGIS/
 │       └── Ancillary/            # UI components and helpers
 ├── configure/                    # Admin configuration interface
 │   └── build/                    # Configuration UI
+├── mcp/                          # MCP server: agents drive MMGIS + generate dashboards
+├── chat/                         # Standalone chat UI: OpenAI-driven MMGIS control via the MCP server
 ├── docs/                         # Documentation (Jekyll site)
 ├── public/                       # Static assets
 ├── Missions/                     # Mission data storage

API/Backend/Config/routes/configs.js

@@ -14,6 +14,7 @@ const Config = require("../models/config");
 const config_template = require("../../../templates/config_template");
 const userModel = require("../../Users/models/user");
 const User = userModel.User;
+const { isSuperAdminRequest } = require("../../Utils/permissions");
 
 // Sanitize user input to prevent XSS in error messages
 function sanitizeInput(input) {
@@ -381,7 +382,8 @@ function add(req, res, next, cb) {
 
 if (fullAccess)
   router.post("/add", function (req, res, next) {
-    if (req.session.permission !== "111") {
+    const isSuperAdmin = isSuperAdminRequest(req);
+    if (!isSuperAdmin) {
       res.send({
         status: "failure",
         message: "Only SuperAdmins can add new missions.",

API/Backend/Users/routes/users.js

@@ -11,6 +11,7 @@ const buf = crypto.randomBytes(128);
 const logger = require("../../../logger");
 const userModel = require("../models/user");
 const User = userModel.User;
+const { isSuperAdminRequest } = require("../../Utils/permissions");
 
 function isStrongPassword(password) {
   const minLength = 8;
@@ -81,12 +82,12 @@ router.post("/first_signup", function (req, res, next) {
 router.post("/signup", function (req, res, next) {
   if (
     (process.env.AUTH === "local" &&
-      req.session.permission !== "111" &&
+      !isSuperAdminRequest(req) &&
       !(
         process.env.AUTH_LOCAL_ALLOW_SIGNUP === true ||
         process.env.AUTH_LOCAL_ALLOW_SIGNUP === "true"
       )) ||
-    (process.env.AUTH === "off" && req.session.permission !== "111")
+    (process.env.AUTH === "off" && !isSuperAdminRequest(req))
   ) {
     res.send({
       status: "failure",

API/Backend/Users/setup.js

@@ -5,7 +5,12 @@ const userModel = require("./models/user");
 let setup = {
   //Once the app initializes
   onceInit: (s) => {
-    s.app.use(s.ROOT_PATH + "/api/users", s.checkHeadersCodeInjection, router);
+    s.app.use(
+      s.ROOT_PATH + "/api/users",
+      s.checkHeadersCodeInjection,
+      s.annotateLongTermToken,
+      router
+    );
   },
   //Once the server starts
   onceStarted: (s) => {},

API/Backend/Utils/permissions.js

@@ -0,0 +1,7 @@
+function isSuperAdminRequest(req) {
+  return (
+    (req.session && req.session.permission === "111") ||
+    (req.isLongTermToken === true && req.tokenUserPermission === "111")
+  );
+}
+module.exports = { isSuperAdminRequest };

chat/.env.example

@@ -0,0 +1,22 @@
+# Your OpenAI API key (required). Never sent to the browser.
+OPENAI_API_KEY=sk-...
+OPENAI_MODEL=gpt-4o
+CHAT_PORT=8895
+
+# How to launch the MMGIS MCP server (relative paths resolve against chat/)
+MCP_COMMAND=node
+MCP_ARGS=../mcp/dist/index.js
+
+# Passed through to the MCP server process.
+# MMGIS_URL is YOUR running MMGIS instance (whatever PORT its .env uses; 8888 by default).
+# MMGIS_TOKEN is an MMGIS API token you generate yourself: log into MMGIS as an
+# admin, open the Configure page, and use the "API Tokens" tab. It is not a
+# shared secret — each person mints their own, and it inherits that account's
+# permissions (creating missions needs a SuperAdmin token).
+MMGIS_URL=http://localhost:8888
+MMGIS_TOKEN=
+MAPBOX_TOKEN=
+
+# Where the dashboard UI is served, if different from MMGIS_URL
+# (in dev, webpack serves the UI on PORT+1 and its redirect drops query params)
+MMGIS_DASHBOARD_URL=http://localhost:8889

chat/.gitignore

@@ -0,0 +1,2 @@
+node_modules/
+.env

chat/README.md

@@ -0,0 +1,73 @@
+# MMGIS Chat UI
+
+A standalone chat app for driving MMGIS with your own OpenAI key: describe a
+dashboard, watch the MCP tools fire, open the result, and steer the live map —
+all from a browser chat.
+
+## Quickstart
+
+1. Build the MCP server once: `cd ../mcp && npm install && npm run build`
+2. `cd chat && npm install`
+3. `cp .env.example .env` and set:
+   - `OPENAI_API_KEY` — your own OpenAI key (stays server-side, never sent to the browser)
+   - `MMGIS_URL` — your running MMGIS instance, e.g. `http://localhost:8888`
+   - `MMGIS_TOKEN` — an MMGIS API token you generate in MMGIS's **Configure →
+     API Tokens** tab (each person mints their own; it inherits that account's
+     permissions, and creating missions needs a SuperAdmin token)
+4. `npm start` → open http://localhost:8895
+
+## What you can do
+
+- "Create an air quality dashboard over Atlanta" → watch `catalog_*` +
+  `dashboard_generate` fire; click "Open dashboard →".
+- "Show me the config JSON for that dashboard" → the model calls
+  `dashboard_generate` with `returnConfig: true`; copy the JSON from the tool card.
+- **JSON config** drawer → paste/edit config JSON, name it, "Create dashboard
+  from JSON" (runs `dashboard_create_from_config` through the agent, visibly).
+- With a dashboard open in another tab: "fly the map to Huntsville" (`view_*`
+  tools drive that session over the MMGIS websocket).
+- "Make the OSM layer 50% transparent", "rename the page to Flood Watch then reload the view", "upload this GeoJSON and add it as a layer", "delete the JSON Demo mission" → live config editing and confirmation workflows.
+
+## How it works
+
+Browser (static page, SSE) → `server.js` (Express; your key stays here) →
+OpenAI function calling → MCP client over stdio → `../mcp/dist/index.js` →
+MMGIS REST + websocket. Conversation state lives in your browser
+(localStorage); the server is stateless.
+
+## Env vars
+
+| Var | Default | Purpose |
+| --- | --- | --- |
+| `OPENAI_API_KEY` | (required) | Server-side only |
+| `OPENAI_MODEL` | `gpt-4o` | Chat model |
+| `CHAT_PORT` | `8895` | UI port |
+| `MCP_COMMAND` / `MCP_ARGS` | `node` / `../mcp/dist/index.js` | MCP server launch (paths relative to `chat/`) |
+| `MMGIS_URL` | `http://localhost:8888` | Your running MMGIS instance |
+| `MMGIS_TOKEN` | — | MMGIS API token (Configure → API Tokens) |
+| `MAPBOX_TOKEN`, `STAC_CATALOGS`, ... | — | Passed through to the MCP server |
+
+## Known limitations
+
+- Cross-turn memory only replays user/assistant text — tool results are not
+  persisted between turns. If you need the model to recall a config from
+  earlier in the conversation, ask it to echo the config back rather than
+  relying on it to remember the raw tool output.
+- Very large configs may not round-trip faithfully through the JSON drawer
+  (the model can hit output length limits when repeating them back).
+
+## Manual E2E checklist
+
+- [ ] `/api/health` shows the model and `MCP connected` with 28 tools
+- [ ] Simple prompt streams a text reply
+- [ ] Dashboard request shows tool cards and an "Open dashboard →" button that loads in MMGIS
+- [ ] "show me the config JSON" returns the full config in a tool card
+- [ ] JSON drawer creates a mission from pasted (edited) config
+- [ ] `view_fly_to` request visibly moves an open dashboard's map
+- [ ] Bad OpenAI key shows a red error bubble, conversation survives a retry
+- [ ] layer_update from chat visibly changes an open dashboard WITHOUT reloading (e.g. opacity)
+- [ ] mission_update_config + view_reload applies a basemap/page-name change
+- [ ] geodataset_ingest (inline) → layer_add with geodatasets:<name> renders the data
+- [ ] mission_delete asks for confirmation in chat before acting
+- [ ] user_create + user_set_permission work with the long-term token (exercises the flagged backend change)
+- [ ] mission_clone (may fail if the MMGIS host lacks a `python` binary — record outcome)

chat/lib/agentLoop.js

@@ -0,0 +1,85 @@
+export const SYSTEM_PROMPT = `You are an assistant that builds and drives MMGIS dashboards through tools.
+
+Workflow guidance:
+- Before generating a dashboard, call dashboard_profile_schema (input shape + layer examples) and dashboard_tool_options (valid tool names).
+- Find data layers with catalog_collections / catalog_search, and convert items with catalog_item_to_layer.
+- Catalog dataset names are technical, not thematic: for "air quality" search no2, so2, pm, aerosol; for "wildfire" search fire, burn, thermal. Try 2-3 synonyms and scan the availableCollections list before concluding no data exists.
+- When a request is thematic ("flooding", "fires") and several distinct datasets match, DO NOT silently pick one. Present a short numbered list of the best candidates — plain-language title, whether it is event-specific (small area, days) or ongoing/global (use temporalExtent/spatialExtent), and dates — then ask the user to choose before building. Skip asking only when the request is already specific or exactly one reasonable match exists. Always state in your final summary exactly which datasets you used.
+- Mission names must avoid punctuation (letters, numbers, spaces, underscores are safe).
+- After dashboard_generate or dashboard_create_from_config succeeds, ALWAYS give the user the mission URL.
+- When the user wants to see or edit the raw config, call dashboard_generate with returnConfig: true and show the JSON.
+- When the user provides config JSON, install it with dashboard_create_from_config. For an EXISTING mission, apply provided JSON as a mission_update_config patch instead (merge semantics: absent keys survive, null deletes); dashboard_create_from_config is for new missions.
+- Use view_* tools to drive a browser session that has the mission open (view_get_state first if unsure).
+- Tool errors include a "hint" — follow it to self-correct. If you cannot recover, tell the user the error and hint plainly.
+- Editing existing dashboards: prefer layer_add/layer_update/layer_remove and tool_toggle. For anything else use mission_update_config with a JSON merge-patch (null deletes a key; arrays replace). Edits apply live — layer edits AND config patches — so there's no need to call view_reload after every edit; it remains available as a manual fallback if a session doesn't pick up the change.
+- DESTRUCTIVE tools (mission_delete, geodataset_delete, user_create, user_set_permission) return needsConfirmation first. Show the user exactly what will happen, get their explicit yes, then retry with confirm: true. Never set confirm on your own.
+- Geodata: ingest GeoJSON with geodataset_ingest (inline for small data, url for hosted files), then add a layer with type "vector" and url "geodatasets:<name>".
+- User management: new users start as Viewer (001); promote with user_set_permission (110 Admin / 001 Viewer; SuperAdmin cannot be granted). Never repeat passwords back.
+- If earlier messages in this conversation claimed data was unavailable, do not trust that claim — catalogs and tools improve; re-search fresh each time the user asks.
+- Be concise. Never invent tool results.`
+
+export async function runAgentLoop({ messages, openai, bridge, model, onEvent, maxIterations = 15 }) {
+    const tools = await bridge.getOpenAiTools()
+    const convo = [{ role: 'system', content: SYSTEM_PROMPT }, ...messages]
+
+    for (let i = 0; i < maxIterations; i++) {
+        const { text, toolCalls } = await streamOneTurn({ openai, model, messages: convo, tools, onEvent })
+        if (toolCalls.length === 0) {
+            onEvent({ type: 'done' })
+            return
+        }
+        convo.push({
+            role: 'assistant',
+            content: text || null,
+            tool_calls: toolCalls.map((c) => ({
+                id: c.id,
+                type: 'function',
+                function: { name: c.name, arguments: c.args },
+            })),
+        })
+        for (const c of toolCalls) {
+            let parsed = null
+            try {
+                parsed = c.args ? JSON.parse(c.args) : {}
+            } catch {}
+            onEvent({ type: 'tool_call', id: c.id, name: c.name, args: parsed ?? {} })
+            const result =
+                parsed === null
+                    ? { text: JSON.stringify({ error: `Invalid JSON arguments: ${c.args}` }), isError: true }
+                    : await bridge.callTool(c.name, parsed)
+            onEvent({ type: 'tool_result', id: c.id, name: c.name, result: result.text, isError: result.isError })
+            convo.push({ role: 'tool', tool_call_id: c.id, content: result.text })
+        }
+    }
+
+    // Loop guard: force a final, tool-free summary
+    convo.push({ role: 'user', content: 'Tool budget exhausted — summarize what you did and stop.' })
+    await streamOneTurn({ openai, model, messages: convo, onEvent })
+    onEvent({ type: 'done' })
+}
+
+async function streamOneTurn({ openai, model, messages, tools, onEvent }) {
+    const stream = await openai.chat.completions.create({
+        model,
+        messages,
+        stream: true,
+        ...(tools ? { tools } : {}),
+    })
+    let text = ''
+    const toolCalls = []
+    for await (const chunk of stream) {
+        const delta = chunk.choices?.[0]?.delta
+        if (!delta) continue
+        if (delta.content) {
+            text += delta.content
+            onEvent({ type: 'text', delta: delta.content })
+        }
+        for (const tc of delta.tool_calls || []) {
+            const slot = (toolCalls[tc.index] ??= { id: '', name: '', args: '' })
+            if (tc.id) slot.id = tc.id
+            if (tc.function?.name) slot.name += tc.function.name
+            if (tc.function?.arguments) slot.args += tc.function.arguments
+        }
+    }
+    return { text, toolCalls: toolCalls.filter(Boolean) }
+}

chat/lib/app.js

@@ -0,0 +1,71 @@
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import express from 'express'
+import { runAgentLoop } from './agentLoop.js'
+
+const PUBLIC_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'public')
+
+export function createApp({ cfg, openai, bridge }) {
+    const app = express()
+    app.use(express.json({ limit: '2mb' }))
+    app.use(express.static(PUBLIC_DIR))
+
+    app.get('/api/health', async (req, res) => {
+        let toolCount = 0
+        try {
+            toolCount = (await bridge.getOpenAiTools()).length
+        } catch {
+            // leave toolCount 0; mcpConnected reflects reality below
+        }
+        res.json({
+            ok: true,
+            model: cfg.model,
+            mcpConnected: bridge.isConnected(),
+            toolCount,
+            mmgisUrl: cfg.mcpEnv?.MMGIS_URL ?? null,
+            // Where the dashboard UI is served (webpack dev server differs from the API port)
+            dashboardUrl: cfg.mcpEnv?.MMGIS_DASHBOARD_URL ?? cfg.mcpEnv?.MMGIS_URL ?? null,
+        })
+    })
+
+    app.get('/api/missions', async (req, res) => {
+        try {
+            const out = await bridge.callTool('mission_list', {})
+            if (out.isError) return res.status(502).json({ error: out.text })
+            res.json({ missions: JSON.parse(out.text).missions ?? [] })
+        } catch (err) {
+            res.status(502).json({ error: String(err?.message ?? err) })
+        }
+    })
+
+    app.get('/api/tools', async (req, res) => {
+        try {
+            const tools = await bridge.getOpenAiTools()
+            res.json({ tools: tools.map((t) => ({ name: t.function.name, description: t.function.description })) })
+        } catch (err) {
+            res.status(502).json({ error: err.message })
+        }
+    })
+
+    app.post('/api/chat', async (req, res) => {
+        const { messages } = req.body || {}
+        const valid =
+            Array.isArray(messages) &&
+            messages.every((m) => m && typeof m.content === 'string' && ['user', 'assistant'].includes(m.role))
+        if (!valid) {
+            return res.status(400).json({ error: 'body must be {messages: [{role: user|assistant, content: string}]}' })
+        }
+        res.setHeader('Content-Type', 'text/event-stream')
+        res.setHeader('Cache-Control', 'no-cache')
+        res.setHeader('Connection', 'keep-alive')
+        const send = (event) => res.write(`data: ${JSON.stringify(event)}\n\n`)
+        try {
+            await runAgentLoop({ messages, openai, bridge, model: cfg.model, onEvent: send })
+        } catch (err) {
+            send({ type: 'error', message: String(err?.message ?? err) })
+        }
+        res.end()
+    })
+
+    return app
+}

chat/lib/config.js

@@ -0,0 +1,18 @@
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+export function loadConfig(env = process.env) {
+    if (!env.OPENAI_API_KEY) {
+        throw new Error('OPENAI_API_KEY is required — copy chat/.env.example to chat/.env and set it')
+    }
+    return {
+        apiKey: env.OPENAI_API_KEY,
+        model: env.OPENAI_MODEL || 'gpt-4o',
+        port: parseInt(env.CHAT_PORT || '8895', 10),
+        mcpCommand: env.MCP_COMMAND || 'node',
+        mcpArgs: (env.MCP_ARGS || '../mcp/dist/index.js').split(' ').filter(Boolean),
+        // chat/lib -> chat/
+        mcpCwd: path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..'),
+        mcpEnv: { ...env },
+    }
+}