gia-mcp-server 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -1,47 +1,30 @@
-# Changelog
-
-All notable changes to GIA MCP Server will be documented in this file.
-
-## [0.1.0] - 2026-02-08
-
-### Initial Release
-
-#### Governance Engine
-- MAI Framework classification (Mandatory/Advisory/Informational)
-- Context-aware elevation rules (PII, financial impact, legal impact, client-facing)
-- Domain-specific escalation (healthcare, veterans, legal, finance, defense)
-
-#### Forensic Ledger
-- Hash-chained, append-only audit trail (SHA-256)
-- Chain integrity verification
-- Operation-based and time-range querying
-
-#### Human-in-the-Loop Gates
-- MANDATORY gate enforcement with pending approval tracking
-- Gate approval/rejection with rationale capture
-- Audit trail for all gate decisions
-
-#### Governance Scoring
-- Three-dimensional scoring: Integrity (40%), Accuracy (35%), Compliance (25%)
-- Weighted composite with pass/fail and letter grades (A+ through F)
-- Threshold-based recommendations
-
-#### Storey Threshold
-- Governance health metric measuring MANDATORY escalation rate
-- Healthy band: 10-18%
-- Status levels: HEALTHY, DEGRADED, CRITICAL
-
-#### Compliance Mapping
-- NIST AI RMF (8 controls)
-- EU AI Act (8 articles)
-- ISO/IEC 42001 (6 controls)
-- NIST SP 800-53 (11 controls)
-
-#### EU AI Act Risk Assessment
-- Four-tier risk classification (Unacceptable, High, Limited, Minimal)
-- Governance and documentation requirements per tier
-- Domain-aware assessment
-
-#### MCP Transport
-- 10 MCP tools via stdio transport
-- Compatible with Claude Desktop and Claude Code
+# Changelog
+
+All notable changes to GIA MCP Server will be documented in this file.
+
+## [0.2.0] - 2026-02-25
+
+### Changed
+- **Architecture**: Package is now a thin proxy to the hosted GIA server at `gia.aceadvising.com`
+- All governance logic executes server-side
+- Requires `GIA_API_KEY` environment variable for authentication
+
+### Added
+- Dynamic tool discovery (tools are fetched from the server — no package update needed when new tools are added)
+- Bearer token authentication via API key
+- Configurable server URL via `GIA_SERVER_URL` environment variable
+- 29 governance tools available (up from 10 in v0.1.0)
+- MCP tool annotations (readOnlyHint, destructiveHint, idempotentHint)
+- Support for MCP resources and prompts
+
+### Removed
+- Local governance engine (all logic is now server-side)
+
+## [0.1.0] - 2026-02-09
+
+### Initial Release
+- Local governance engine with 10 MCP tools
+- MAI Framework classification
+- Forensic audit ledger
+- Governance scoring
+- Compliance mapping

package/LICENSE

@@ -1,53 +1,54 @@
-GIA MCP Server — Proprietary Software License
-
-Copyright (c) 2025-2026 William J. Storey III / ACE Advising
-All Rights Reserved.
-
-NOTICE: This software and all associated documentation, algorithms,
-frameworks, and intellectual property (collectively, "the Software")
-are the proprietary property of William J. Storey III / ACE Advising.
-
-GRANT OF USE:
-You may install and use the Software in its compiled/distributed form
-for the purpose of governance and compliance operations within your
-own organization, subject to the following restrictions.
-
-RESTRICTIONS:
-1. You may NOT modify, reverse-engineer, decompile, or disassemble
-   the Software or any portion thereof.
-2. You may NOT redistribute, sublicense, sell, lease, or transfer
-   the Software to any third party without prior written consent.
-3. You may NOT create derivative works based on the Software.
-4. You may NOT remove or alter any proprietary notices, labels,
-   or marks on the Software.
-5. You may NOT use the Software to build a competing product
-   or service.
-
-INTELLECTUAL PROPERTY:
-The following concepts, algorithms, and frameworks embodied in the
-Software are the intellectual property of the author:
-- MAI Framework (Mandatory/Advisory/Informational classification)
-- Storey Threshold (governance health metric, 10-18% escalation band)
-- Forensic Ledger (hash-chained, append-only audit architecture)
-- Governance Scoring Engine (Integrity/Accuracy/Compliance weighted composite)
-- GIA Governance Architecture (the layered governance-as-code pattern)
-
-DISCLAIMER:
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
-CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
-TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
-SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-
-TERMINATION:
-This license terminates automatically if you violate any of its terms.
-Upon termination, you must destroy all copies of the Software in
-your possession.
-
-For licensing inquiries, partnership opportunities, or enterprise
-agreements, contact:
-
-William J. Storey III
-ACE Advising
+GIA MCP Server — Proprietary Software License
+
+Copyright (c) 2025-2026 William J. Storey III / ACE Advising
+All Rights Reserved.
+
+NOTICE: This software and all associated documentation, algorithms,
+frameworks, and intellectual property (collectively, "the Software")
+are the proprietary property of William J. Storey III / ACE Advising.
+
+GRANT OF USE:
+You may install and use the Software in its compiled/distributed form
+for the purpose of governance and compliance operations within your
+own organization, subject to the following restrictions.
+
+RESTRICTIONS:
+1. You may NOT modify, reverse-engineer, decompile, or disassemble
+   the Software or any portion thereof.
+2. You may NOT redistribute, sublicense, sell, lease, or transfer
+   the Software to any third party without prior written consent.
+3. You may NOT create derivative works based on the Software.
+4. You may NOT remove or alter any proprietary notices, labels,
+   or marks on the Software.
+5. You may NOT use the Software to build a competing product
+   or service.
+
+INTELLECTUAL PROPERTY:
+The following concepts, algorithms, and frameworks embodied in the
+Software are the intellectual property of the author:
+- MAI Framework (Mandatory/Advisory/Informational classification)
+- Storey Threshold (governance health metric)
+- Forensic Ledger (hash-chained, append-only audit architecture)
+- Governance Scoring Engine (weighted composite scoring)
+- GIA Governance Architecture (the layered governance-as-code pattern)
+
+DISCLAIMER:
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+TERMINATION:
+This license terminates automatically if you violate any of its terms.
+Upon termination, you must destroy all copies of the Software in
+your possession.
+
+For licensing inquiries, partnership opportunities, or enterprise
+agreements, contact:
+
+William J. Storey III
+ACE Advising
+https://gia.aceadvising.com

package/README.md

@@ -1,280 +1,142 @@
-# GIA MCP Server
-
-**Governance layer for Claude AI agents.** Classify every decision, enforce human approval gates, score outputs, and maintain a cryptographic audit trail — all through Anthropic's Model Context Protocol.
-
-```
-Claude Agent ──> GIA MCP Server ──> Governed Decision
-                     │
-                     ├── MAI Classification (Mandatory/Advisory/Informational)
-                     ├── Human-in-the-Loop Gate (blocks until approved)
-                     ├── Governance Scoring (Integrity/Accuracy/Compliance)
-                     ├── Forensic Ledger (SHA-256 hash-chained audit)
-                     └── Compliance Mapping (NIST, EU AI Act, ISO 42001)
-```
-
----
-
-## Why
-
-Every enterprise deploying Claude agents needs to answer three questions:
-
-1. **What did the agent decide?** (Classification)
-2. **Was a human involved?** (Gates)
-3. **Can you prove it?** (Audit trail)
-
-GIA answers all three at runtime, not after the fact.
-
----
-
-## Install
-
-### Option 1: Claude Desktop
-
-Add to your Claude Desktop config (`claude_desktop_config.json`):
-
-```json
-{
-  "mcpServers": {
-    "gia": {
-      "command": "npx",
-      "args": ["gia-mcp-server"]
-    }
-  }
-}
-```
-
-Config file location:
-- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
-- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
-
-### Option 2: Claude Code
-
-Add to your project settings (`.claude/settings.local.json`):
-
-```json
-{
-  "mcpServers": {
-    "gia": {
-      "command": "npx",
-      "args": ["gia-mcp-server"]
-    }
-  }
-}
-```
-
-Or install globally and point to the binary:
-
-```bash
-npm install -g gia-mcp-server
-```
-
-```json
-{
-  "mcpServers": {
-    "gia": {
-      "command": "gia-mcp-server"
-    }
-  }
-}
-```
-
-### Option 3: From source
-
-```bash
-git clone https://github.com/aceadvising/gia-mcp-server.git
-cd gia-mcp-server
-npm install
-npm start
-```
-
----
-
-## Tools
-
-GIA exposes 10 MCP tools. Once connected, Claude can call them directly.
-
-### classify_decision
-
-Classify any AI agent decision using the MAI Framework.
-
-```
-"Classify this decision: Delete all veteran records older than 5 years"
-
-→ MANDATORY | Confidence: 0.92 | Gate Required: Yes
-  Rationale: Decision pattern matches MANDATORY threshold
-  Pending Gate ID: GATE-1707350400-a1b2c3
-```
-
-**MAI Framework:**
-
-| Level | Behavior | Example |
-|-------|----------|---------|
-| **MANDATORY** | Blocks until human approves | Delete records, submit claims, deploy to production |
-| **ADVISORY** | Logs with recommendation, continues | Search queries, draft documents, rank results |
-| **INFORMATIONAL** | Audit trail only | Status checks, read operations |
-
-Context always **elevates**, never reduces. PII detected? Elevated to MANDATORY. Financial impact? MANDATORY. Client-facing? MANDATORY.
-
-### score_governance
-
-Score any agent output on three dimensions:
-
-```
-"Score this operation: integrity=0.92, accuracy=0.88, compliance=0.95"
-
-→ Composite: 0.912 | Grade: A | Pass: Yes
-  Weights: Integrity 40% | Accuracy 35% | Compliance 25%
-```
-
-| Score | Action |
-|-------|--------|
-| 0.70+ | Release (pass) |
-| 0.50-0.70 | Repair required |
-| Below 0.50 | Halt operations |
-
-### evaluate_threshold
-
-The Storey Threshold measures governance health by tracking MANDATORY escalation rate.
-
-```
-"Evaluate the governance threshold"
-
-→ Escalation Rate: 14.2% | Status: HEALTHY
-  Recommendation: Within optimal band (10-18%). System is calibrated.
-```
-
-| Rate | Status | Meaning |
-|------|--------|---------|
-| Below 10% | DEGRADED | Under-classifying risks |
-| 10-18% | HEALTHY | Appropriately calibrated |
-| 18-25% | DEGRADED | Over-classifying, unnecessary friction |
-| Above 25% | CRITICAL | System bottlenecked |
-
-### approve_gate
-
-Human-in-the-loop approval for MANDATORY decisions.
-
-```
-"List pending gates"
-→ 1 pending gate: GATE-1707350400-a1b2c3
-
-"Approve gate GATE-1707350400-a1b2c3 rationale: Verified retention policy"
-→ Status: APPROVED | Approved by: operator
-```
-
-### audit_pipeline
-
-Query the hash-chained forensic ledger. Every entry is cryptographically linked to the previous (SHA-256). Tamper with one, the chain breaks.
-
-### assess_risk_tier
-
-EU AI Act risk classification (Unacceptable, High, Limited, Minimal) with governance and documentation requirements per tier.
-
-### map_compliance
-
-Map GIA controls to regulatory frameworks:
-- **NIST AI RMF** — GOVERN, MAP, MEASURE, MANAGE
-- **EU AI Act** — Articles 9, 10, 11, 12, 13, 14, 15, 52
-- **ISO/IEC 42001** — AI management system
-- **NIST SP 800-53** — Security and privacy controls
-
-### monitor_agents
-
-Health status for all governed agents.
-
-### generate_report
-
-Governance status report: threshold health, compliance coverage, agent states, operational metrics.
-
-### system_status
-
-Full system snapshot: uptime, ledger state, configuration, governance module status.
-
----
-
-## Architecture
-
-```
-┌──────────────────────────────────────────────────────────┐
-│  Claude Desktop / Claude Code  (MCP Client)               │
-└──────────────────────┬───────────────────────────────────┘
-                       │ stdio
-┌──────────────────────▼───────────────────────────────────┐
-│  GIA MCP Server                                           │
-│                                                           │
-│  ┌─────────────────────────────────────────────────────┐ │
-│  │  Transport Layer (MCP Protocol)                      │ │
-│  │  10 tools | validate | delegate                      │ │
-│  └─────────────────────┬───────────────────────────────┘ │
-│                         │                                 │
-│  ┌─────────────────────▼───────────────────────────────┐ │
-│  │  Governance Engine                                   │ │
-│  │                                                      │ │
-│  │  MAI Classifier ── Gate Enforcer ── Forensic Ledger  │ │
-│  │  Scoring Engine ── Storey Threshold ── Compliance    │ │
-│  └─────────────────────────────────────────────────────┘ │
-└──────────────────────────────────────────────────────────┘
-```
-
-**Design principles:**
-- Transport layer does zero business logic
-- Every operation writes to the forensic ledger
-- Classification is deterministic (pattern matching + rules, not LLM-based)
-- Audit entries are hash-chained (SHA-256)
-- Zero external dependencies beyond `@modelcontextprotocol/sdk`
-
----
-
-## Concepts
-
-### MAI Framework
-
-Every AI agent decision is classified as **Mandatory**, **Advisory**, or **Informational**:
-
-- **MANDATORY** — Blocks execution until a human approves through the gate. Deletions, submissions, deployments, financial transactions, PII operations.
-- **ADVISORY** — Logs a recommendation, continues execution. Searches, drafts, rankings, analysis.
-- **INFORMATIONAL** — Audit trail entry only. Status checks, read operations, internal routing.
-
-Context elevates, never reduces. A search (ADVISORY) that touches PII becomes MANDATORY.
-
-### Storey Threshold
-
-A quantitative health metric. Measures what percentage of decisions require MANDATORY classification.
-
-- Too low (<10%): Rubber-stamping. Critical decisions aren't being caught.
-- Healthy (10-18%): Appropriate friction. Most decisions flow; critical ones stop.
-- Too high (>18%): Bottleneck. Trust calibration needed.
-
-### Forensic Ledger
-
-Append-only, hash-chained audit trail. Every entry contains:
-- Operation name and timestamp
-- MAI classification level
-- Input/output hashes (SHA-256)
-- Chain link to previous entry
-
-Verify chain integrity at any time. If any entry is modified, the chain breaks.
-
----
-
-## Limitations (v0.1)
-
-| Works | Not yet |
-|-------|---------|
-| MAI classification with elevation rules | No persistent storage (in-memory, resets on restart) |
-| Human-in-the-loop gate enforcement | No auth on MCP transport |
-| SHA-256 hash-chained audit trail | No distributed deployment |
-| Governance scoring with pass/fail | No rate limiting |
-| Storey Threshold health monitoring | Compliance mappings are static |
-| 4-framework compliance mapping | Single vertical (ACE/VA claims) |
-| EU AI Act risk assessment | No database persistence |
-
-Known gaps with planned solutions. Governance engine is fully functional.
-
----
-
-## License
-
-Proprietary. Copyright (c) 2025-2026 William J. Storey III / ACE Advising. All rights reserved.
-
-The MAI Framework, Storey Threshold, Forensic Ledger architecture, and GIA governance patterns are intellectual property of the author. See [LICENSE](LICENSE) for terms.
+# GIA MCP Server
+
+[![npm version](https://img.shields.io/npm/v/gia-mcp-server)](https://www.npmjs.com/package/gia-mcp-server)
+[![License](https://img.shields.io/badge/license-proprietary-blue)](LICENSE)
+[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
+[![MCP](https://img.shields.io/badge/protocol-MCP-purple)](https://modelcontextprotocol.io)
+
+**Governance Intelligence Architecture** — the governance layer for Claude AI agents.
+
+This package connects [Claude Desktop](https://claude.ai/download) and [Claude Code](https://docs.anthropic.com/en/docs/claude-code) to the hosted GIA governance engine, giving your AI workflows enterprise-grade governance: decision classification, forensic audit trails, human-in-the-loop gates, compliance mapping, and more.
+
+Built on Anthropic's [Model Context Protocol](https://modelcontextprotocol.io).
+
+## Why GIA?
+
+AI agents are powerful — but **ungoverned AI agents are a liability**. GIA solves this by providing:
+
+- **Decision Classification** — Every AI decision is classified as Mandatory (human required), Advisory (human optional), or Informational (agent autonomous)
+- **Forensic Audit Trail** — Hash-chained, tamper-evident ledger of every operation, decision, and gate approval
+- **Human-in-the-Loop Gates** — High-impact actions require explicit human approval before execution
+- **Compliance Mapping** — Map governance controls to NIST AI RMF, EU AI Act, ISO 42001, and NIST 800-53
+- **Governed Memory** — Hash-sealed knowledge packs with trust levels, TTL, and role-based access
+
+GIA is the governance layer that makes Claude deployments enterprise-ready.
+
+## Quick Start
+
+### 1. Get an API Key
+
+Visit [gia.aceadvising.com](https://gia.aceadvising.com) to create an account and generate an API key.
+
+### 2. Configure Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "gia": {
+      "command": "npx",
+      "args": ["-y", "gia-mcp-server"],
+      "env": {
+        "GIA_API_KEY": "gia_your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+### 3. Configure Claude Code
+
+```bash
+claude mcp add gia -- npx -y gia-mcp-server
+```
+
+Then set your API key in your environment:
+
+```bash
+export GIA_API_KEY=gia_your_api_key_here
+```
+
+## How It Works
+
+```
+Claude Desktop/Code  <--stdio-->  gia-mcp-server  <--HTTPS-->  gia.aceadvising.com
+     (MCP Client)                  (this package)               (Governance Engine)
+```
+
+This package is a lightweight proxy. All governance logic runs on the hosted GIA server — nothing is computed locally. When you add new tools or capabilities on the server, they appear automatically without updating this package.
+
+## Available Tools
+
+### Governance Core
+| Tool | Description |
+|------|-------------|
+| `classify_decision` | Classify an AI agent decision using the MAI Framework |
+| `score_governance` | Compute weighted governance score from integrity, accuracy, and compliance values |
+| `evaluate_threshold` | Compute the Storey Threshold — governance health metric |
+| `assess_risk_tier` | Assess AI system risk tier with governance recommendations |
+| `map_compliance` | Map governance components to regulatory compliance frameworks |
+| `approve_gate` | Approve or reject a pending mandatory gate decision (human-in-the-loop) |
+
+### Audit & Monitoring
+| Tool | Description |
+|------|-------------|
+| `audit_pipeline` | Query the hash-chained forensic audit ledger |
+| `verify_ledger` | Verify integrity of the audit ledger hash chain |
+| `generate_report` | Generate a governance status report |
+| `system_status` | Get full system health and configuration |
+| `monitor_agents` | Monitor status and health of governed AI agents |
+
+### Governed Memory Packs
+| Tool | Description |
+|------|-------------|
+| `seal_memory_pack` | Create a hash-sealed Governed Memory Pack |
+| `load_memory_pack` | Load a memory pack into agent context with validation |
+| `transfer_memory_pack` | Transfer a memory pack between agents via governed corridor |
+| `compose_memory_packs` | Compose multiple memory packs into a unified context |
+| `distill_memory_pack` | Distill governance patterns from usage history |
+| `promote_memory_pack` | Promote a memory pack to a higher trust level |
+
+### Site Reliability
+| Tool | Description |
+|------|-------------|
+| `srt_run_watchdog` | Submit health check results to the SRT Watchdog |
+| `srt_diagnose` | Run diagnostician on an incident |
+| `srt_approve_repair` | Approve or reject a pending repair plan |
+| `srt_generate_postmortem` | Generate a structured postmortem report |
+
+### Infrastructure Operations
+| Tool | Description |
+|------|-------------|
+| `gia_scan_environment` | Detect target environment (OS, containers, services) |
+| `gia_list_packs` | List available operations packs |
+| `gia_dry_run_pack` | Preview pack execution with blast radius analysis |
+| `gia_apply_pack` | Execute a remediation or hardening pack |
+| `gia_run_patrol` | Execute read-only patrol or audit checks |
+
+### Value & Impact
+| Tool | Description |
+|------|-------------|
+| `record_value_metric` | Record a workflow value metric for ROI reporting |
+| `record_governance_event` | Record a governance event |
+| `generate_impact_report` | Generate economic and governance impact report |
+
+## Configuration
+
+| Environment Variable | Required | Default | Description |
+|---------------------|----------|---------|-------------|
+| `GIA_API_KEY` | Yes | — | Your GIA API key |
+| `GIA_SERVER_URL` | No | `https://gia.aceadvising.com/mcp` | Custom server URL |
+
+## Requirements
+
+- Node.js 18 or later
+- A GIA API key ([get one here](https://gia.aceadvising.com))
+
+## License
+
+Proprietary. See [LICENSE](LICENSE) for details.
+
+Copyright (c) 2025-2026 William J. Storey III / ACE Advising

package/bin/gia-mcp-server.js

@@ -1,20 +1,2 @@
-#!/usr/bin/env node
-
-/**
- * GIA MCP Server — CLI Entry Point
- *
- * Governance Intelligence Architecture
- * Built on Anthropic's Model Context Protocol
- *
- * Copyright (c) 2025-2026 William J. Storey III / ACE Advising
- * All rights reserved. See LICENSE for details.
- */
-
-import { fileURLToPath } from 'node:url';
-import { dirname, join } from 'node:path';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-// Load the compiled server
-await import(join(__dirname, '..', 'dist', 'index.js'));
+#!/usr/bin/env node
+import '../dist/proxy.js';

package/dist/proxy.d.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * GIA MCP Server — Proxy
+ *
+ * Transparent MCP bridge that connects Claude Desktop / Claude Code
+ * to the hosted GIA governance engine at gia.aceadvising.com.
+ *
+ * All governance logic executes server-side. This package contains
+ * zero governance algorithms — it is a pure protocol relay.
+ *
+ * Architecture:
+ *   Claude <--stdio--> this proxy <--HTTPS--> gia.aceadvising.com/mcp
+ *
+ * @author ACE Advising
+ * @version 0.2.0
+ */
+export {};