AI Governance MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@AI Governance MCP Serverhow do I handle incomplete specifications?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Open-source meta-framework. This repository is the public extract of the AI Governance framework: the governance engine, the constitution + rules of procedure (meta-framework), and infrastructure. Subject-matter domains (AI coding, multi-agent, etc.) are maintained privately and are not included here.
AI Governance MCP Server
A semantic retrieval system that gives AI assistants on-demand access to domain-specific governance principles — a queryable "second brain" of encoded standards.
Why this exists
The engineering stack for AI systems has five layers:
Prompt engineering — how you phrase the request (role, task, instructions, output format).
Retrieval engineering — how you get your information into the AI (RAG, vector search, semantic and hybrid indexing, reranking).
Context engineering — what you put in front of the model for the task at hand (memory, conversation history, tool outputs, retrieved material).
Harness engineering — the environment you build around the model so it can't repeat its mistakes (orchestration, guardrails, approval gates, feedback loops, evaluation, observability, durable state).
Intent engineering — principles, methods, and enforcement that run across every layer. What the system is optimizing for, including in cases no one anticipated.
The first four form a structural stack — each layer contains the ones below it. Intent engineering runs across all of them, defining what the system is ultimately trying to accomplish. Without it, the other layers optimize without knowing what for.
Most AI tools stop at the first three. They phrase prompts, retrieve reference material, and assemble context. They don't tell the AI what judgment to apply — which standards matter, which constraints can't be traded off, what "done" looks like.
This project is infrastructure for the intent layer. It doesn't make AI smarter. It encodes the principles and methods that define what good work looks like, makes them retrievable at the moment of the AI's decision through MCP tools, and gates file-modifying actions on prior consultation through hooks.
For the founding intent in the author's voice, see the Declaration in documents/constitution.md.
Related MCP server: standards-mcp
The Problem
AI assistants are powerful, but without structured guidance they can:
Hallucinate requirements instead of asking for clarification
Skip validation steps in complex workflows
Apply inconsistent approaches across similar problems
Miss critical safety considerations
Loading full governance documents (~55K+ tokens) into context is wasteful and often exceeds limits. Simple keyword search misses semantically related concepts.
The Solution
This MCP server provides hybrid semantic retrieval of governance principles:
Near-zero miss rate in hybrid retrieval for in-domain queries — combined keyword + semantic search with reranking. See
tests/benchmarks/for formal Recall@K measurements on a fixed query set.Sub-100ms retrieval latency in typical use on a developer laptop; reproduce via
python -m ai_governance_mcp.server --test "<query>".Smart domain routing — automatic identification of relevant knowledge domains.
Cross-encoder reranking — most relevant principles surface first.
Query: "how do I handle incomplete specifications?"
→ Routes to: ai-coding domain
→ Returns: coding-context-specification-completeness with HIGH confidence
→ Time: 45ms
Query: "help me develop my protagonist's character arc"
→ Routes to: storytelling domain
→ Returns: storytelling-ST3-transformation-arc with HIGH confidence
→ Time: 48msThe Governance Framework
Most people use AI as-is. This project implements a systematic governance framework that is retrievable, auditable, and structurally enforceable at the moment of the AI's decision — then operationalizes it through an MCP server.
The framework uses a 7-layer governance hierarchy modeled on the US Constitutional system: immutable Safety Principles (Bill of Rights), Constitution, Domain Statutes, Rules of Procedure, Domain Regulations, Tool SOPs, and accumulating Secondary Authority (Reference Library). See documents/constitution.md for the full operative hierarchy and the Declaration of founding intent.
Available Domains
Domains are modular and self-describing. The system discovers domains automatically from the documents/ directory — drop in a title-NN-domainname.md file with YAML frontmatter and the server picks it up. Remove a file and the domain disappears. No registry edits, no code changes.
Shipped domains:
Domain | Principles | Methods | Coverage |
Constitution | 24 | 332 | Universal AI behavior, safety, quality |
AI Coding | 16 | 340 | Software development, testing, deployment |
Multi-Agent | 17 | 54 | Agent orchestration, handoffs, autonomous operation |
Storytelling | 15 | 35 | Creative writing, narrative, voice preservation |
Multimodal RAG | 32 | 65 | Image retrieval, visual presentation, agentic retrieval |
UI/UX | 20 | 47 | Visual hierarchy, accessibility, interaction design |
KM&PD | 10 | 37 | Knowledge management, people development, training |
Accounting | 12 | 29 | Double-entry bookkeeping, reconciliation, tax prep, QBO integration |
SaaS Operations | 0 | 13 | Production-ops failure-class gates (deploy, payments, RLS, secrets, durability) for a founder/small-team + AI without an SRE team — methods-only |
Visual Communication | 10 | 10 | Static artifact design — decks, reports, spreadsheets, tables/charts: signal discipline, answer-first structure, assertion-evidence slides, workbook segregation, display integrity, perceptual access (document accessibility) |
Create
documents/title-NN-yourdomain.mdwith YAML frontmatter:--- domain: "your-domain" prefix: "yd" display_name: "Your Domain" description: "Keywords for semantic domain routing..." priority: 50 ---Optionally create
documents/title-NN-yourdomain-cfr.mdfor methods (discovered by convention).Rebuild the index:
python -m ai_governance_mcp.extractorRestart the server.
list_domainsnow includes your domain.
Frontmatter fields: domain (required — the machine name), prefix (principle ID prefix, e.g. "yd" → IDs like yd-category-title), display_name (human-readable), description (used for semantic domain routing — include keywords for your domain's topics), priority (sort order; 0 = highest). An optional domains.json can override any frontmatter field without editing the markdown files.
Removing a domain: Delete or move the title-NN-*.md file. Rebuild the index and restart.
Architecture
Component | Technology | Purpose |
Server | MCP Python SDK | Official MCP SDK ( |
Embeddings | sentence-transformers ( | Semantic similarity |
Keyword Search | rank-bm25 | BM25 keyword matching |
Reranking | CrossEncoder | Result refinement |
Data Models | Pydantic | Validation & typing |
Storage | In-memory (NumPy) | Fast retrieval |
Build Time:
documents/*.md → extractor.py → global_index.json + embeddings.npy
Runtime:
Query → Domain Router → Hybrid Search → Reranker → Hierarchy Filter → Results
(semantic) (BM25+semantic) (cross-encoder)Retrieval pipeline:
Domain Routing — query embedding similarity identifies relevant domains
Hybrid Search — BM25 (keywords) + dense vectors (semantic) in parallel
Score Fusion — weighted combination (60% semantic, 40% keyword)
Reranking — cross-encoder scores top 20 candidates
Hierarchy Filter — S-Series (safety) always prioritized
How It Works
23 MCP Tools (2 Servers)
Governance Server (16 tools):
Tool | Purpose |
| Pre-action compliance check — PROCEED/MODIFY/ESCALATE |
| Main retrieval with confidence scores |
| Post-action audit verification |
| Search Reference Library for implementation precedent |
| Full content by ID (principles, methods, and references) |
| Available domains with stats |
| Domain exploration |
| Quality tracking |
| Performance analytics |
| Install governance subagent (Claude Code only) |
| Remove installed subagent |
| Discover available agents (cross-platform) |
| Record per-principle reasoning traces for audit |
| Create governance memory files for new projects |
| Create Reference Library entries from real application |
| Read precomputed feedback loop analysis of server logs |
Context Engine Server (7 tools):
Tool | Purpose |
| Semantic + keyword search across project content |
| Trigger re-index of current project |
| Show all indexed projects |
| Index stats for current project |
| Structural code references — who imports/calls/extends a symbol |
| Build LLM-based knowledge graph from indexed content (opt-in, has LLM cost) |
| Query the knowledge graph for entity/relationship information |
Governance enforcement:
evaluate_governanceevaluates planned actions against principles BEFORE execution, auto-detects S-Series (safety) concerns, and returns PROCEED, REVIEW, or ESCALATE. REVIEW means relevant principles were surfaced — read and apply them. S-Series violations force ESCALATE with human review. Every call logs anaudit_id.verify_governance_compliancechecks whether governance was consulted for a completed action — catches bypassed checks after the fact.log_governance_reasoningcaptures per-principle reasoning traces for the audit trail.
Subagent installation (Claude Code):
The install_agent tool provides 10 specialized subagents:
orchestrator — governance coordination (ensures
evaluate_governance()is called)code-reviewer — fresh-context code review against explicit criteria
security-auditor — OWASP-aligned vulnerability detection
test-generator — behavior-focused test creation
documentation-writer — technical writing specialist
validator — criteria-based quality validation
contrarian-reviewer — devil's advocate for high-stakes decisions
coherence-auditor — documentation drift detection
continuity-auditor — narrative consistency verification
voice-coach — character voice distinction analysis
Other platforms receive agent definitions as adaptable reference material via install_agent.
Example Usage
Add the MCP server to your AI assistant's configuration:
{
"mcpServers": {
"ai-governance": {
"command": "python",
"args": ["-m", "ai_governance_mcp.server"]
}
}
}Then the AI invokes governance automatically:
User: "I need to implement a login system"
AI uses query_governance("implementing authentication system")
→ Returns coding-quality-security-first-development + coding-context-specification-completeness
→ AI knows to: verify security requirements, ask about auth method preferencesResults
Metric | Target | Observed (approximate) |
Miss Rate | <1% | Near-zero on in-domain queries (hybrid retrieval; see |
Latency | <100ms | ~50ms typical (author-observed on a developer laptop) |
Token Savings | >90% | ~98% (1-3K retrieved vs 55K+ if full docs loaded into context) |
Test Coverage | 80% | ~90% governance, ~65% context engine (run |
Metrics are author-observed on a developer laptop and are not a controlled benchmark. Reproduce via
pytest --covfor coverage,python -m ai_governance_mcp.server --test "<query>"for retrieval latency, andtests/benchmarks/for formal retrieval-quality measurements.
Quick Start
Clone, install, and configure:
git clone https://github.com/jason21wc/ai-governance-mcp.git
cd ai-governance-mcp
pip install -e .
python -m ai_governance_mcp.extractor # Build the search indexThen use the config generator to set up your AI client:
python -m ai_governance_mcp.config_generator --platform claude # Claude Code CLI
python -m ai_governance_mcp.config_generator --platform cursor # Cursor
python -m ai_governance_mcp.config_generator --platform windsurf # Windsurf
python -m ai_governance_mcp.config_generator --all # All platformsTest: "Query governance for handling incomplete specifications".
First Five: Critical Reasoning Disciplines
Every evaluate_governance call returns a critical 5 scaffold — the five reasoning disciplines most often violated in practice, selected by learning log failure frequency and user feedback patterns. These are delivered as reasoning scaffolds ("demonstrate this thinking") rather than checklists ("did you do this?"). The full universal floor (defined in documents/tiers.json) has additional constitutional principles, method references, and a subagent-applicability check.
Rule | What it asks of the AI | Canonical reference |
Find the structural cause | What system, process, or design produced this? Name the structural cause, not the visible symptom. Your fix should target that. | principle: |
Verify before acting | What assumption are you making right now? How have you confirmed it — from the actual source, not a review note or agent convergence? | principle: |
State what you don't know | Where is your uncertainty? Name it explicitly before proceeding. "I don't know" is a successful output. | principle: |
Make the call | Present your best recommendation with rationale. Don't ask what you should decide. Don't defer what you can resolve now. | behavioral: |
Match effort to stakes | Is this a 3-file fix or a new subsystem? Act on what it actually is, not what it might theoretically become. | behavioral: |
Use get_principle for principle IDs. Methods like §7.8 are found through query_governance, which lists them by id and title — method bodies are not inlined, so fetch the procedure itself with get_principle using the id the query returned:
get_principle("meta-core-systemic-thinking")
query_governance("proportional rigor") # lists method ids + titles
get_principle("meta-method-progressive-application-proportional-response") # §7.8 itselfPrinciple bodies, by contrast, come back in full from query_governance within a size budget. Anything withheld or truncated is named explicitly with the get_principle call that retrieves it, so a partial answer never looks like a complete one.
Sample queries to run on day one (each surfaces additional floor items beyond the table above — e.g., the second query exercises the testing-integration method):
query_governance("how do I handle incomplete specifications")
query_governance("when should I write tests")
query_governance("how to do a security review")
query_governance("refactoring approach for legacy code")
evaluate_governance(planned_action="ship a new feature to production")Once these feel natural, the full hierarchy in documents/constitution.md becomes navigable rather than imposing — you'll already recognize the principles you're being asked to extend.
Use via RAG (No MCP Server)
If you already have a RAG infrastructure or want to use the governance content in a non-MCP environment (ChatGPT Custom GPT, Claude Projects, Perplexity Spaces, NotebookLM, OpenAI Assistants, custom bots), you can load the documents/ folder directly as a knowledge source — no server, no hooks, no installation.
Pattern:
Clone or download the
documents/folder from this repo.Load
documents/ai-instructions.mdinto your platform's system prompt or "AI Instructions" field — it tells the AI how to consult the governance content.Load the rest of
documents/*.md(constitution, rules-of-procedure, title-NN-*.md) as the reference/knowledge corpus.
Platform mapping:
Platform | Instructions field → | Knowledge/sources → other |
ChatGPT Custom GPT | "Instructions" field | "Knowledge" file uploads |
Claude Projects | Project system prompt | Project knowledge |
Perplexity Spaces | "AI Instructions" | Uploaded files |
OpenAI Assistants API |
| File Search tool |
NotebookLM | (use first message as instructions) | Source documents |
Poe / custom bots | System prompt | Vector store |
Note on platform instruction-field limits: documents/ai-instructions.md is ~230 lines with structured XML-tag blocks. ChatGPT Custom GPT "Instructions" fields cap at 8K characters; Perplexity Spaces is tighter. If your platform's instruction field is too small, paste only the <primary_directive> + <first_response_protocol> + <mcp_integration> blocks into Instructions, and move the rest (hierarchy, memory-architecture, version-reference tables) into the knowledge corpus.
Trade-off (be explicit about it):
✅ You get: principles + methods content, retrieval grounding, the AI can cite specific principles by name.
❌ You don't get:
evaluate_governancescoring + S-Series veto, hierarchy filter,verify_governance_complianceaudit trail, the structural hook enforcement that blocks unconsulted file-modifying actions, or the 10 installable subagents.
In 5-layer terms: you're adopting the intent-engineering content with your own retrieval engineering around it. You're skipping the harness-engineering layer the MCP server provides. Fine for advisory use and assistants that summarize or answer questions; not sufficient when you need deterministic blocking of risky actions in an autonomous agent.
License: Framework content (documents/) is CC BY-NC-ND 4.0 — attribution required, non-commercial use only, no derivatives (you may load the files as reference; you may not modify and redistribute). Code (src/) is Apache-2.0. See LICENSE-CONTENT for the framework-content license terms.
Platform Configuration
Use the config generator for platform-specific setup — it resolves an absolute interpreter path (so GUI hosts like Claude Desktop launch it without needing your shell PATH) and writes the AI_GOVERNANCE_* environment variables. It defaults to advisory (the server alone); pass --enforce to wrap it in the governance proxy (soft mode):
python -m ai_governance_mcp.config_generator --platform claude # Claude Code CLI
python -m ai_governance_mcp.config_generator --platform gemini # Gemini CLI
python -m ai_governance_mcp.config_generator --platform chatgpt # ChatGPT Desktop
python -m ai_governance_mcp.config_generator --platform cursor # Cursor
python -m ai_governance_mcp.config_generator --platform windsurf # Windsurf
python -m ai_governance_mcp.config_generator --all # All platforms
python -m ai_governance_mcp.config_generator --json claude # JSON output
python -m ai_governance_mcp.config_generator --json claude --enforce # Wrap in the proxy (soft mode)The config generator automatically includes
AI_GOVERNANCE_INDEX_PATHandAI_GOVERNANCE_DOCUMENTS_PATHenvironment variables. These are required when running the server from a different directory than the project root.
Web-based platforms (Perplexity, Grok, Google AI Studio): use the MCP SuperAssistant Chrome Extension to bridge MCP to web clients.
Claude Code CLI and Claude Desktop have separate MCP configurations. If you use both, configure each independently.
Enforcement Proxy
The enforcement proxy (ai-governance-proxy) wraps the governance MCP server at the protocol level, intercepting JSON-RPC tool calls. In hard mode it blocks an action tool that lacks a prior evaluate_governance() call; in soft mode it only appends a warning and lets the call through. Important: this gates the model's call order — it is model-satisfiable (the model can call evaluate_governance() itself), not a human approval gate. On auto-running GUI hosts (Claude Desktop) a soft warning is post-hoc, so the host's own per-tool approval prompt is the real human gate (see this note — search_references("ref-ai-coding-connect-local-mcp-server-to-claude-surfaces")). Works with any MCP client: Claude App, Cursor, Gemini CLI, ChatGPT Desktop, and others.
The config generator defaults to advisory (no proxy); pass --enforce to opt in.
Mode | How to configure | What it does | When to use |
Advisory (config-gen default) | Default — | Model cooperation only; the host's own approval prompt is the gate | Any MCP host, incl. GUI |
Proxy, soft |
| Appends a warning, does not block; post-hoc on GUI auto-run | A nudge for hookless clients |
Proxy, hard | proxy + | Blocks an action tool until | Clients without their own gate |
Graduating to hard mode: enable the proxy (--enforce) and set GOVERNANCE_ENFORCEMENT_SOFT_MODE=false in your MCP config's env block. Action tools are then blocked (not just warned) until evaluate_governance() is called — a call-order gate, still model-satisfiable rather than a human approval step.
Phase 2 — Cross-MCP enforcement: The proxy can also wrap third-party MCP servers (GitHub, filesystem, etc.) to enforce governance before any consequential tool call. See API.md for --govern-all mode and config file format.
Key environment variables:
Variable | Default | Description |
|
| Master toggle |
|
| Warn instead of block |
|
| Tool calls before governance expires |
Full enforcement architecture: EXECUTION-FRAMEWORK.md §8.4. CLI reference: API.md § Enforcement Proxy.
Local Installation
For development or customization:
git clone https://github.com/jason21wc/ai-governance-mcp.git
cd ai-governance-mcp
pip install -e . # install with dependencies
python -m ai_governance_mcp.extractor # build the index (first time)
python -m ai_governance_mcp.server # run the serverQuick test:
python -m ai_governance_mcp.server --test "how do I handle incomplete specs"Configuration
Governance Server environment variables:
export AI_GOVERNANCE_DOCUMENTS_PATH=/path/to/documents
export AI_GOVERNANCE_INDEX_PATH=/path/to/index
export AI_GOVERNANCE_EMBEDDING_MODEL=BAAI/bge-small-en-v1.5
export AI_GOVERNANCE_SEMANTIC_WEIGHT=0.6Context Engine Server environment variables:
export AI_CONTEXT_ENGINE_EMBEDDING_MODEL=BAAI/bge-small-en-v1.5
export AI_CONTEXT_ENGINE_EMBEDDING_DIMENSIONS=384
export AI_CONTEXT_ENGINE_SEMANTIC_WEIGHT=0.7
export AI_CONTEXT_ENGINE_INDEX_PATH=~/.context-engine/indexes
export AI_CONTEXT_ENGINE_INDEX_MODE=realtime # 'ondemand' or 'realtime' (file watcher)
export AI_CONTEXT_ENGINE_READONLY=auto # 'true', 'false', or 'auto' (sandbox detection)
# Knowledge Graph (optional — requires pip install -e ".[knowledge-graph]")
export AI_CONTEXT_ENGINE_COGNEE_LLM_PROVIDER=ollama # 'ollama', 'anthropic', 'openai'
export AI_CONTEXT_ENGINE_COGNEE_LLM_MODEL= # provider-dependent model name
export AI_CONTEXT_ENGINE_COGNEE_LLM_API_KEY= # required for cloud providers
export AI_CONTEXT_ENGINE_COGNEE_LLM_ENDPOINT= # custom endpoint (non-default Ollama port, Azure, OpenAI-compatible)
export AI_CONTEXT_ENGINE_COGNEE_LLM_TEMPERATURE= # LLM temperature (default: 0.0; >0 may produce non-reproducible entity graphs)
export AI_CONTEXT_ENGINE_COGNEE_EMBEDDING_PROVIDER=fastembed
export AI_CONTEXT_ENGINE_COGNEE_EMBEDDING_MODEL= # falls back to AI_CONTEXT_ENGINE_EMBEDDING_MODEL, then BAAI/bge-small-en-v1.5
export AI_CONTEXT_ENGINE_COGNEE_EMBEDDING_DIMENSIONS= # falls back to AI_CONTEXT_ENGINE_EMBEDDING_DIMENSIONS, then 384Knowledge Graph Model Recommendations
The build_knowledge_graph tool uses an LLM to extract entities and relationships from indexed content. Model choice affects extraction quality, speed, and cost. Cognee uses the instructor structured output framework by default, which works with all recommended models.
How to choose — the trade-offs are stable even though the models and prices are not, so this section describes the shape of the decision and sends you to the vendor for current values. (Model names, prices, and benchmark scores were previously tabulated here and rotted on four vendors' independent release cadences; see rules-of-procedure §10.1.4.)
Local — zero marginal cost, recommended for development. Any instruction-tuned open model that supports grammar-constrained JSON will work. The axis that matters is memory: a mixture-of-experts model in the ~20 GB class gives the best quality-per-second because only a fraction of its parameters activate per token, a dense model of similar footprint reasons better per token but runs slower, and a large dense model gives the highest local quality at the cost of needing 64 GB+ of unified memory. Constrain JSON output via Outlines (LM Studio) or GBNF (Ollama) — extraction quality depends far more on that than on model choice.
# Local via LM Studio (MLX acceleration on Apple Silicon)
export AI_CONTEXT_ENGINE_COGNEE_LLM_PROVIDER=custom
export AI_CONTEXT_ENGINE_COGNEE_LLM_MODEL=<your-local-model-id>
export AI_CONTEXT_ENGINE_COGNEE_LLM_ENDPOINT=http://127.0.0.1:1234/v1
export AI_CONTEXT_ENGINE_COGNEE_LLM_API_KEY=.
# Local via Ollama (GGUF)
export AI_CONTEXT_ENGINE_COGNEE_LLM_PROVIDER=ollama
export AI_CONTEXT_ENGINE_COGNEE_LLM_MODEL=<your-ollama-model-tag>Cloud. A knowledge-graph build is a high-volume, low-difficulty extraction job — many small structured-output calls, not deep reasoning. The small/fast tier of any major vendor is the right default, and the frontier tier is not worth its multiple here. Cost scales with corpus size: a build over a few hundred chunks lands in single-digit dollars on the small tier and roughly an order of magnitude more on the frontier tier. Read current per-token prices from the vendor's own pricing page — they change more often than this file does.
# Cloud — small/fast tier of any provider
export AI_CONTEXT_ENGINE_COGNEE_LLM_PROVIDER=openai
export AI_CONTEXT_ENGINE_COGNEE_LLM_MODEL=<small-tier-model-id>
export AI_CONTEXT_ENGINE_COGNEE_LLM_API_KEY=sk-...Before you commit to a model, test structured output on ten chunks. Structured-output reliability varies by vendor and generation and is the failure mode that actually bites here — a model that reasons well but emits malformed JSON is useless for this job. That check costs pennies and is worth more than any recommendation this file could carry.
Context Engine Server
The Context Engine is a separate MCP server that provides semantic search across your project's source code and documents. It complements the Governance Server by providing project-specific content awareness.
Aspect | Governance Server | Context Engine |
Content | Governance principles & methods | Your project's files |
Index | Pre-built, ships with image | Built per-project on first use |
Purpose | "What should I do?" | "What exists and where?" |
Quick setup (ask your AI coding assistant to run these):
claude mcp add ai-context-engine -- python -m ai_governance_mcp.context_engine.server
context-engine-service install --projects /path/to/your/project
context-engine-service statusThe watcher daemon keeps indexes fresh automatically. It auto-restarts every ~12h (configurable via --max-uptime-hours) to flush the PyTorch CPU allocator cache. Platform-specific service installation: LaunchAgent (macOS), systemd user service (Linux), Task Scheduler (Windows).
Sandboxed environments (Cowork, Docker, CI): the engine auto-detects read-only filesystems and enters read-only mode — queries work against pre-built indexes; writes are blocked. Pattern: index once, query everywhere. Build indexes from a writable environment; all environments query the same indexes at ~/.context-engine/indexes/.
Features: file watcher with debounce/cooldown, circuit breaker on consecutive failures, hybrid search (semantic + keyword), code/markdown/PDF/spreadsheet/image support, .contextignore file support, atomic file writes, corrupt file recovery, LRU project eviction.
Troubleshooting
"0 domains" or empty principles: CLI and Desktop configs are separate systems. Check both have AI_GOVERNANCE_DOCUMENTS_PATH and AI_GOVERNANCE_INDEX_PATH set.
S-Series false positives: evaluate_governance flags safety-adjacent keywords in planned_action text. Most keyword-only triggers (a CRITICAL keyword matched but no S-Series principle retrieved) are now handled server-side: the keyword adjudicator (BACKLOG #73, active by default) routes benign topic mentions to REVIEW instead of ESCALATE. If you still see s_series_check.triggered=true with empty principles, check keyword_adjudication: genuine or floor means a real concern — do NOT override; unavailable (judge unreachable) is the fail-safe heuristic case (document the override in your reasoning trace and proceed).
CI failing on hook tests: hooks require shell matching Bash|Edit|Write. Verify .claude/settings.json PreToolUse matcher includes all three.
Index stale after document edit: the extractor rebuilds the full index in ~30 seconds. For incremental updates during development, restart the MCP server — indexes are in-memory and reload on server start.
Project Structure
ai-governance-mcp/
├── src/ai_governance_mcp/
│ ├── models.py # Pydantic data structures
│ ├── config.py # Settings management
│ ├── extractor.py # Document parsing + embeddings
│ ├── retrieval.py # Hybrid search engine
│ ├── server/ # Governance MCP server + 16 tools (package)
│ ├── config_generator.py # Multi-platform MCP configs
│ ├── validator.py # Principle ID validation
│ └── context_engine/ # Context Engine MCP (7 tools)
├── documents/ # Governance documents (Constitutional naming)
│ ├── constitution.md # Meta-Principles (Articles I-IV, Bill of Rights)
│ ├── rules-of-procedure.md # Constitution Methods (amendment process, authoring)
│ ├── title-NN-domain.md # Domain principles (Federal Statutes)
│ ├── title-NN-domain-cfr.md # Domain methods (Code of Federal Regulations)
│ └── domains.json # Optional domain overrides (domains discovered from files)
├── .claude/skills/ # Project skills (completion-sequence-aigov, compliance-review, test-authoring)
├── global-skills/ # Canonical source for user-level skills (content-enhancer, code-review, dream, …)
├── reference-library/ # Accumulating applied patterns (secondary authority)
├── .claude/
│ ├── agents/ # Installed subagents
│ └── hooks/ # Enforcement hooks (PreToolUse, UserPromptSubmit, SessionStart, pre/post-push gates)
├── index/ # Generated index + embeddings
└── tests/ # Test suite (governance + context engine; run pytest for the current count)Dogfooding
This project is built using its own governance framework. Development follows the AI Coding framework (SPECIFY → PLAN → TASKS → IMPLEMENT) encoded in documents/title-10-ai-coding.md, with explicit gate criteria per phase. Decisions are logged through evaluate_governance + log_governance_reasoning. The framework's own hooks enforce governance consultation on source edits to this repo. Lessons from applying the framework to itself are captured in LEARNING-LOG.md — including corrections when the framework fails its own standards.
Development
pip install -e ".[dev]" # install dev dependencies
pre-commit install # enable pre-commit hooksTest suite covers governance (~90% coverage) and context engine (~65%). Run pytest --collect-only -q | tail -1 for current count.
pytest tests/ -v # full suite
pytest -m "not slow" tests/ # fast tests only (skip real ML models)
pytest --cov=ai_governance_mcp --cov-report=html tests/ # coverage report
pytest -m real_index tests/ # real-index tests onlyTests include real index validation and actual ML model tests (marked @pytest.mark.slow).
Security scanning (included in dev dependencies):
pip-audit # scan dependencies for vulnerabilities
bandit -r src/ # scan source code for security issues
safety check # check for known vulnerabilitiesRoadmap
Distribution & Deployment
pip install (editable and wheel)
Public API with authentication
Architecture Enhancements
AI-driven modification assessment (hybrid: script-layer S-Series detection + AI-layer principle conflict analysis)
Improved method embedding quality (MRR 0.0 → 0.698)
Context Engine MCP server with watcher daemon
Governance effectiveness measurement (see BACKLOG.md #22 for scope)
Content
Shipped domains (see the domain table above) + modular custom domain support (drop in
title-NN-name.md, rebuild index)Visual communication domain (presentations, reports, print design — see BACKLOG #6)
Autonomous operations domain (see BACKLOG #11)
Full roadmap discussion and open questions live in BACKLOG.md.
About
Built by Jason as a showcase of:
Semantic retrieval patterns for knowledge-intensive applications
AI governance frameworks for retrievable, enforceable governance principles
MCP integration for extending AI assistant capabilities
The governance framework itself is the key innovation — the MCP server is its operational implementation.
Built with the AI Governance Framework — Constitution, Rules of Procedure, and modular domain statutes. See documents/ai-instructions.md for current domain versions.
License
This project uses dual licensing:
Source code (
src/,tests/,scripts/, build files): Apache License 2.0Framework content (
documents/,index/): CC BY-NC-ND 4.0 — Copyright (c) 2026 Jason Collier
This server cannot be deployed
Maintenance
Related MCP Connectors
Shared semantic graph for AI reviews, classification and structured memory across AI assistants.
Governance layer for AI coding agents: knowledge-graph grounding, session audit, policy controls.
Governance maturity assessment, compliance gap analysis, and evidence-linked briefs for AI agents.
Runtime AI governance: decision gates, human approval, hash-chained audit, compliance mapping.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables AI systems to remember interactions, understand document context through semantic search, and intelligently route requests with persistent memory and quality-scored content synthesis.-
- AlicenseNot gradedqualityCmaintenanceTransforms static coding standards into a queryable live data store for AI agents, delivering task-specific rules and fix guidance on demand. This optimizes context window usage through progressive disclosure, ensuring agents apply relevant governance without loading massive documentation.2MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI-powered access to authoritative design systems knowledge, including W3C standards, WCAG guidelines, and best practices from 188+ curated entries via semantic vector search.4 npm211MIT

brehon-mcp-serverofficial
AlicenseNot gradedqualityDmaintenanceProvides AI assistants with real-time, structured access to 32 privacy and AI governance laws across 28 jurisdictions to prevent hallucination in compliance answers.0MIT