gia-mcp-server 0.3.1 → 0.3.2

package/CHANGELOG.md

@@ -2,46 +2,41 @@
 
 All notable changes to GIA MCP Server will be documented in this file.
 
-## [0.1.0] - 2026-02-08
+## [0.2.2] - 2026-02-26
 
-### Initial Release
+### Fixed
+- Proxy no longer crashes when upstream GIA server is unreachable
+- Server stays alive in disconnected mode — returns clear errors on tool calls
+- Local ping responses keep health checks passing (Glama, monitoring)
+- Lazy reconnect: automatically retries upstream on next tool call
+
+### Changed
+- Stdio transport starts before upstream connection (resilient startup order)
+- Upstream connection failure is now WARNING, not FATAL
+
+## [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
 
-#### 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
+### 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,216 @@
-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
+The MCP project is undergoing a licensing transition from the MIT License to the Apache License, Version 2.0 ("Apache-2.0"). All new code and specification contributions to the project are licensed under Apache-2.0. Documentation contributions (excluding specifications) are licensed under CC-BY-4.0.
+
+Contributions for which relicensing consent has been obtained are licensed under Apache-2.0. Contributions made by authors who originally licensed their work under the MIT License and who have not yet granted explicit permission to relicense remain licensed under the MIT License.
+
+No rights beyond those granted by the applicable original license are conveyed for such contributions.
+
+---
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright
+      owner or by an individual or Legal Entity authorized to submit on behalf
+      of the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+---
+
+MIT License
+
+Copyright (c) 2024-2025 Model Context Protocol a Series of LF Projects, LLC.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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.
+
+---
+
+Creative Commons Attribution 4.0 International (CC-BY-4.0)
+
+Documentation in this project (excluding specifications) is licensed under
+CC-BY-4.0. See https://creativecommons.org/licenses/by/4.0/legalcode for
+the full license text.

package/README.md

@@ -1,280 +1,155 @@
-# 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 Governed Intelligence Architecture
+
+**Enterprise AI governance through the Model Context Protocol.**
+
+GIA is a production governance engine that gives AI agents enforceable decision controls, compliance scoring, immutable audit chains, and human-in-the-loop gates. Built for organizations operating under NIST, FedRAMP, CMMC, EU AI Act, and SOC 2 requirements.
+
+29 MCP tools. One integration point. Works with Claude Desktop, Claude Code, OpenAI Agent Builder, and any MCP-compatible client.
+
+## Quick Start
+
+```bash
+npx gia-mcp-server
+```
+
+Or install globally:
+
+```bash
+npm install -g gia-mcp-server
+gia-mcp-server
+```
+
+The server connects to the hosted GIA engine at `https://gia.aceadvising.com`. Configure your API key:
+
+```bash
+GIA_API_KEY=your-key npx gia-mcp-server
+```
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "gia-governance": {
+      "command": "npx",
+      "args": ["-y", "gia-mcp-server"],
+      "env": {
+        "GIA_API_KEY": "your-key"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add gia-governance -- npx -y gia-mcp-server
+```
+
+### OpenAI Agent Builder
+
+Point to the Streamable HTTP endpoint:
+
+```
+https://gia.aceadvising.com/mcp
+```
+
+### Smithery
+
+```
+npx -y @smithery/cli install @knowledgepa3/gia-mcp-server --client claude
+```
+
+## Tools
+
+### Decision Controls (MAI Framework)
+
+| Tool | Description |
+|------|-------------|
+| `classify_decision` | Classify agent decisions as Mandatory, Advisory, or Informational |
+| `approve_gate` | Human-in-the-loop approval for Mandatory gates |
+| `evaluate_threshold` | Compute escalation health (Storey Threshold) |
+| `score_governance` | Weighted governance scoring (Integrity, Accuracy, Compliance) |
+
+### Compliance & Audit
+
+| Tool | Description |
+|------|-------------|
+| `audit_pipeline` | Query the hash-chained forensic audit ledger |
+| `verify_ledger` | Verify SHA-256 chain integrity from genesis |
+| `map_compliance` | Map controls to NIST AI RMF, EU AI Act, ISO 42001, NIST 800-53 |
+| `assess_risk_tier` | EU AI Act risk tier classification |
+| `generate_report` | Governance status reports (summary, detailed, executive) |
+
+### Knowledge Packs
+
+| Tool | Description |
+|------|-------------|
+| `seal_memory_pack` | Create immutable, TTL-bound knowledge artifacts |
+| `load_memory_pack` | Load packs with trust level and role enforcement |
+| `transfer_memory_pack` | Governed knowledge transfer between agents |
+| `compose_memory_packs` | Merge packs with risk contamination rules |
+| `distill_memory_pack` | Extract governance patterns from usage history |
+| `promote_memory_pack` | Promote packs to higher trust levels after review |
+
+### Security & Operations
+
+| Tool | Description |
+|------|-------------|
+| `monitor_agents` | Agent health, repair history, failure counts |
+| `srt_run_watchdog` | Infrastructure health probes (API, disk, memory, TLS, DB, DNS) |
+| `srt_diagnose` | Incident diagnosis with playbook matching |
+| `srt_approve_repair` | Human-approved repair execution |
+| `srt_generate_postmortem` | Structured incident postmortems with TTD/TTR metrics |
+
+### Infrastructure Remediation
+
+| Tool | Description |
+|------|-------------|
+| `gia_scan_environment` | Scout swarm for environment detection |
+| `gia_list_packs` | List remediation, patrol, hardening, and audit packs |
+| `gia_dry_run_pack` | Preview pack execution with blast radius analysis |
+| `gia_apply_pack` | Execute remediation with mandatory human approval |
+| `gia_run_patrol` | Read-only posture checks and compliance audits |
+
+### Impact & Value
+
+| Tool | Description |
+|------|-------------|
+| `record_value_metric` | Track time saved, risks blocked, autonomy levels |
+| `record_governance_event` | Log gates, drift prevention, violations blocked |
+| `generate_impact_report` | Economic + governance ROI reporting |
+| `system_status` | Engine health, uptime, configuration |
+
+## Architecture
+
+GIA enforces governance through three layers:
+
+1. **Decision Controls** — MAI classification gates side effects and high-impact actions
+2. **Step Hooks** — Workflow progression control at each pipeline stage
+3. **Kernel Hooks** — Resource control at the LLM boundary, including sub-agents
+
+Every governance action is recorded in a SHA-256 hash-chained audit ledger that can be independently verified.
+
+## Compliance Coverage
+
+- **NIST AI RMF** — Risk management framework mapping
+- **EU AI Act** — Risk tier assessment and control mapping
+- **ISO 42001** — AI management system alignment
+- **NIST 800-53** — Federal security control mapping
+- **CMMC 2.0** — DoD cybersecurity maturity
+- **FedRAMP** — Federal cloud authorization
+- **SOC 2** — Service organization controls
+
+## About
+
+Built by [Advanced Consulting Experts (ACE)](https://aceadvising.com) — a Service-Disabled Veteran-Owned Small Business (SDVOSB).
+
+GIA was designed by William J. Storey III, a 17-year Information System Security Officer with experience across DoD contracts and U.S. Army Ranger Battalion operations. The same discipline applied to securing classified systems now governs AI agent workforces.
+
+## License
+
+MIT

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'));
+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 Advanced Consulting Experts (ACE)
+ * @version 0.2.1
+ */
+export {};

package/dist/proxy.js

@@ -0,0 +1,178 @@
+#!/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 Advanced Consulting Experts (ACE)
+ * @version 0.2.1
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { ListToolsResultSchema, CallToolResultSchema, ListResourcesResultSchema, ReadResourceResultSchema, ListResourceTemplatesResultSchema, ListPromptsResultSchema, GetPromptResultSchema, CompleteResultSchema, EmptyResultSchema, } from '@modelcontextprotocol/sdk/types.js';
+const VERSION = '0.2.2';
+const DEFAULT_SERVER_URL = 'https://gia.aceadvising.com/mcp';
+// Result schema map — tells the SDK how to validate upstream responses
+const RESULT_SCHEMAS = {
+    'tools/list': ListToolsResultSchema,
+    'tools/call': CallToolResultSchema,
+    'resources/list': ListResourcesResultSchema,
+    'resources/read': ReadResourceResultSchema,
+    'resources/templates/list': ListResourceTemplatesResultSchema,
+    'prompts/list': ListPromptsResultSchema,
+    'prompts/get': GetPromptResultSchema,
+    'completion/complete': CompleteResultSchema,
+    'ping': EmptyResultSchema,
+    'logging/setLevel': EmptyResultSchema,
+};
+function log(msg) {
+    process.stderr.write(`[GIA] ${msg}\n`);
+}
+// Upstream connection state
+let upstream = null;
+let upstreamConnected = false;
+async function connectUpstream(apiKey, serverUrl) {
+    log(`Connecting to ${serverUrl}...`);
+    const transport = new StreamableHTTPClientTransport(new URL(serverUrl), {
+        requestInit: {
+            headers: {
+                'Authorization': `Bearer ${apiKey}`,
+            },
+        },
+    });
+    upstream = new Client({ name: 'gia-mcp-proxy', version: VERSION }, { capabilities: {} });
+    try {
+        await upstream.connect(transport);
+        upstreamConnected = true;
+        log('Connected to upstream GIA server.');
+        // Handle upstream errors without crashing
+        transport.onerror = (err) => {
+            log(`Upstream error: ${err.message}`);
+        };
+        transport.onclose = () => {
+            log('Upstream connection closed. Server remains available — reconnect on next request.');
+            upstreamConnected = false;
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        log(`WARNING: Failed to connect to GIA server: ${message}`);
+        log('Server is running in disconnected mode.');
+        log('Tool calls will return errors until upstream is reachable.');
+        upstreamConnected = false;
+    }
+}
+async function main() {
+    // ── Read configuration from environment ──
+    const apiKey = process.env.GIA_API_KEY;
+    const serverUrl = process.env.GIA_SERVER_URL || DEFAULT_SERVER_URL;
+    if (!apiKey) {
+        log('ERROR: GIA_API_KEY environment variable is required.');
+        log('');
+        log('Get your API key at https://gia.aceadvising.com');
+        log('Then set it:');
+        log('  export GIA_API_KEY=gia_your_key_here');
+        log('');
+        log('Or configure it in your Claude Desktop / Claude Code settings.');
+        process.exit(1);
+    }
+    // ── Create local stdio server FIRST (so health checks work) ──
+    const local = new Server({ name: 'gia-mcp-server', version: VERSION }, {
+        capabilities: {
+            tools: {},
+            resources: {},
+            prompts: {},
+        },
+    });
+    // ── Bridge: forward requests to upstream (or return error if disconnected) ──
+    local.fallbackRequestHandler = async (request) => {
+        const method = request.method;
+        const params = request.params ?? {};
+        const schema = RESULT_SCHEMAS[method];
+        if (!schema) {
+            throw new Error(`Unsupported method: ${method}`);
+        }
+        // Ping always succeeds locally — keeps the server alive for health checks
+        if (method === 'ping') {
+            return {};
+        }
+        if (!upstreamConnected || !upstream) {
+            // Try to reconnect on demand
+            await connectUpstream(apiKey, serverUrl);
+        }
+        // When disconnected, return empty results for discovery methods
+        // so health checks and tool listing still work
+        if (!upstreamConnected || !upstream) {
+            const disconnectedMsg = `[GIA disconnected] Connect to ${serverUrl} with a valid GIA_API_KEY to enable tools.`;
+            switch (method) {
+                case 'tools/list':
+                    return { tools: [{ name: 'gia_system_status', description: disconnectedMsg, inputSchema: { type: 'object', properties: {} } }] };
+                case 'resources/list':
+                    return { resources: [] };
+                case 'resources/templates/list':
+                    return { resourceTemplates: [] };
+                case 'prompts/list':
+                    return { prompts: [] };
+                case 'logging/setLevel':
+                    return {};
+                default:
+                    throw new Error('GIA upstream server is not reachable. Check your GIA_API_KEY and network connection. ' +
+                        `Server URL: ${serverUrl}`);
+            }
+        }
+        const result = await upstream.request({ method, params }, schema);
+        return result;
+    };
+    // Forward notifications from Claude to upstream
+    local.fallbackNotificationHandler = async (notification) => {
+        if (!upstreamConnected || !upstream)
+            return;
+        try {
+            await upstream.notification({
+                method: notification.method,
+                params: notification.params,
+            });
+        }
+        catch {
+            // Notifications are fire-and-forget; don't crash on failure
+        }
+    };
+    // ── Start stdio transport ──
+    const stdioTransport = new StdioServerTransport();
+    await local.connect(stdioTransport);
+    log(`GIA Governance MCP Proxy v${VERSION}`);
+    log(`Upstream: ${serverUrl}`);
+    log('Transport: stdio <-> HTTPS');
+    log('Ready.');
+    // ── Now connect upstream (non-fatal) ──
+    await connectUpstream(apiKey, serverUrl);
+    // ── Graceful shutdown ──
+    const shutdown = async () => {
+        log('Shutting down...');
+        try {
+            await local.close();
+            if (upstream)
+                await upstream.close();
+        }
+        catch {
+            // Best-effort cleanup
+        }
+        process.exit(0);
+    };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+}
+main().catch((err) => {
+    const message = err instanceof Error ? err.message : String(err);
+    log(`FATAL: ${message}`);
+    process.exit(1);
+});

package/package.json

@@ -1,20 +1,21 @@
 {
   "name": "gia-mcp-server",
-  "version": "0.3.1",
-  "description": "AI Agent Governance Platform — executable contracts for Claude, OpenAI, and any MCP-compatible agent. MAI classification, forensic audit trails, human-in-the-loop gates, EU AI Act compliance, NIST/SOC 2/CMMC mapping. The governance layer your AI workforce needs.",
+  "version": "0.3.2",
+  "description": "MCP server for GIA Governance — connects Claude Desktop, Claude Code, OpenAI Agent Builder, and any MCP client to the hosted GIA governance engine.",
   "author": {
     "name": "William J. Storey III",
-    "url": "https://github.com/aceadvising"
+    "url": "https://aceadvising.com"
   },
-  "license": "SEE LICENSE IN LICENSE",
+  "license": "MIT",
   "type": "module",
-  "main": "dist/index.js",
+  "main": "dist/proxy.js",
+  "types": "dist/proxy.d.ts",
   "bin": {
     "gia-mcp-server": "bin/gia-mcp-server.js"
   },
   "files": [
-    "dist/index.js",
-    "dist/index.d.ts",
+    "dist/proxy.js",
+    "dist/proxy.d.ts",
     "bin/",
     "LICENSE",
     "README.md",
@@ -25,56 +26,34 @@
     "model-context-protocol",
     "anthropic",
     "claude",
+    "openai",
+    "agent-builder",
     "governance",
-    "audit",
+    "ai-safety",
     "compliance",
-    "nist",
-    "eu-ai-act",
-    "iso-42001",
+    "audit",
     "human-in-the-loop",
-    "ai-safety",
-    "forensic-ledger",
-    "openai",
-    "agent-builder",
-    "ai-governance",
-    "ai-contract",
-    "soc2",
-    "cmmc",
-    "fedramp",
-    "sdvosb"
+    "forensic-ledger"
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/aceadvising/gia-mcp-server"
+    "url": "https://github.com/knowledgepa3/gia-mcp-server"
   },
+  "homepage": "https://gia.aceadvising.com",
+  "mcpName": "io.github.knowledgepa3/gia-mcp-server",
   "engines": {
     "node": ">=18.0.0"
   },
   "scripts": {
     "build": "tsc",
-    "dev": "tsx watch src/mcp/server.ts",
-    "start": "node dist/index.js",
-    "start:http": "node dist/mcp/server-http.js",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:governance": "vitest run tests/core/",
-    "test:integration": "vitest run tests/integration/",
-    "test:smoke": "tsx tests/smoke/live-server.ts",
-    "lint": "eslint src/",
-    "onboard": "tsx src/onboarding/generate-client-config.ts"
+    "start": "node dist/proxy.js",
+    "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0",
-    "pg": "^8.13.0",
-    "uuid": "^9.0.0",
-    "zod": "^3.22.0"
+    "@modelcontextprotocol/sdk": "^1.26.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
-    "@types/pg": "^8.16.0",
-    "@types/uuid": "^9.0.0",
-    "tsx": "^4.0.0",
-    "typescript": "^5.3.0",
-    "vitest": "^3.2.4"
+    "typescript": "^5.3.0"
   }
 }

package/dist/index.d.ts

@@ -1,38 +0,0 @@
-#!/usr/bin/env node
-/**
- * GIA MCP Server — Governed Intelligence Architecture
- *
- * Enterprise-grade Model Context Protocol server exposing GIA governance
- * capabilities. Every tool enforces the MAI framework, produces auditable
- * evidence, and maintains a hash-chained forensic ledger.
- *
- * Architecture:
- * ┌──────────────────────────────────────────────────────────────────┐
- * │  Claude Code / Claude Desktop  (MCP Client)                      │
- * └────────────────────────┬─────────────────────────────────────────┘
- *                          │ stdio / SSE
- * ┌────────────────────────▼─────────────────────────────────────────┐
- * │  GIA MCP Server                                                   │
- * │  ├── classify_decision    MAI classification engine               │
- * │  ├── score_governance     Integrity/Accuracy/Compliance scoring   │
- * │  ├── evaluate_threshold   Storey Threshold health metric          │
- * │  ├── assess_risk_tier     EU AI Act risk categorization           │
- * │  ├── map_compliance       Regulatory framework mapping            │
- * │  ├── audit_pipeline       Forensic ledger query                   │
- * │  ├── approve_gate         MANDATORY gate approval (HITL)          │
- * │  ├── monitor_agents       Agent health and status                 │
- * │  ├── generate_report      Governance status report                │
- * │  └── system_status        Full system health                      │
- * └──────────────────────────────────────────────────────────────────┘
- *
- * SECURITY:
- * - No secrets stored in server code
- * - All ledger entries are hash-chained (SHA-256)
- * - PII is never stored — only hashes
- * - Object.freeze on critical config (tamper-proof)
- * - Negative assurance captured (what DIDN'T happen)
- *
- * @author ACE Advising
- * @version 1.0.0
- */
-export {};