OpenHaus Engineering MCP Server

OpenHaus Engineering System (OHES) — A Model Context Protocol (MCP) server that exposes the OpenHaus Engineering knowledge platform to AI assistants, IDEs, and autonomous engineering agents.

---

Overview

The OpenHaus Engineering MCP Server provides the AI interface to the OpenHaus Engineering System (OHES).

Rather than serving the OpenHaus application itself, this repository acts as the knowledge layer that enables AI tools to understand engineering documentation, architecture, standards, workflows, decisions, and project state.

It provides:

• Repository indexing
• Hybrid keyword and semantic search
• Knowledge graph traversal
• Documentation retrieval
• Engineering workflow tooling
• AI context planning

The server follows the Model Context Protocol (MCP) specification, allowing compatible clients such as MCP Inspector, IDE integrations, Cursor, Claude Desktop, and other MCP-compatible agents to interact with the engineering knowledge base.

---

Project Information

Property	Value
Package	openhaus-mcp
Protocol	Model Context Protocol (MCP)
Specification	https://modelcontextprotocol.io
Language	Python
Python Version	3.13+
Status	Active Development
License	(Add when available)

---

Repository Ecosystem

OpenHaus is organised as multiple repositories, each with a specific responsibility.

Repository	Purpose
openhaus-mcp	MCP server and AI knowledge services (this repository)
openhaus-engineering-system	Engineering documentation, architecture, standards, ADRs, workflows, knowledge base
openhaus-portal	Django application powering the OpenHaus Campus Internet Platform

---

Repository Responsibilities

openhaus-mcp

Provides the AI interface to OHES.

Responsibilities include:

• MCP server
• Tool registration
• Repository indexing
• Search
• Knowledge graph
• Semantic retrieval
• AI planning support

---

openhaus-engineering-system

Contains engineering knowledge only.

Examples include:

• Architecture
• Standards
• ADRs
• Governance
• Workflows
• Documentation
• Engineering reports
• Project manifests
• Knowledge modules

---

openhaus-portal

Contains the actual OpenHaus application.

Responsibilities include:

• Django backend
• REST APIs
• Authentication
• Membership management
• Portal functionality
• User accounts
• Network integration

---

What This Server Does

The MCP server exposes OHES to AI systems.

It enables AI assistants to:

• Index Markdown documentation
• Search engineering knowledge
• Resolve documents by identifier
• Traverse document relationships
• Read project status
• Access ADRs
• Access engineering standards
• Access workflows
• Retrieve architecture documentation
• Refresh repository indexes
• Plan engineering work using repository context

---

What This Server Is NOT

This repository does not contain the OpenHaus application.

It is not responsible for:

• Django code
• React frontend
• APIs
• User management
• Captive Portal logic
• Network infrastructure

Those responsibilities belong to openhaus-portal.

---

High-Level Architecture

                    MCP Clients

      Cursor
      Claude Desktop
      Inspector
      VS Code
      AI Agents
      IDE Integrations

              │
              ▼

        server.py (FastMCP)

              │
              ▼

      ┌───────────────────────┐
      │     MCP Tools          │
      └───────────────────────┘
              │
              ▼

      ┌───────────────────────┐
      │  Knowledge Service     │
      └───────────────────────┘
              │
      ┌───────┼────────┬───────────────┐
      ▼       ▼        ▼               ▼

 RepositoryIndex
 RepositoryGraph
 RepositorySearch
 SemanticSearch
 RepositoryWatcher
 RepositoryState

---

Internal Architecture

server.py
│
├── tools/
│     ├── project.py
│     ├── repository.py
│     ├── documentation.py
│     ├── knowledge.py
│     └── ...
│
└── services/
      ├── KnowledgeService
      ├── RepositoryIndex
      ├── RepositoryGraph
      ├── RepositorySearch
      ├── SemanticSearch
      ├── RepositoryWatcher
      └── RepositoryState

---

Design Principles

The MCP server follows several architectural principles.

Service-Oriented Design

Business logic lives inside services.

Tools should only expose functionality.

---

Shared Repository State

A single RepositoryState instance is shared across the process.

This avoids duplicate indexes and unnecessary memory usage.

---

Incremental Indexing

The repository watcher performs incremental updates whenever possible instead of rebuilding the entire repository.

---

Fault Tolerance

Unreadable or malformed documents are skipped during indexing.

Failures are logged without stopping repository construction.

---

Workspace Layout

Expected workspace:

openHaus Net/
│
├── openhaus-mcp/
│
├── openhaus-engineering-system/
│
└── openhaus-portal/

---

Directory Configuration

Variable	Default
OHES_ROOT	../openhaus-engineering-system
PROJECT_ROOT	OHES_ROOT/projects/openhaus
DOCS_ROOT	OHES_ROOT/docs
KNOWLEDGE_ROOT	OHES_ROOT/knowledge
AUTOMATION_ROOT	OHES_ROOT/automation
PORTAL_ROOT	../openhaus-portal
REPOSITORY_ROOT	OHES_ROOT

All paths can be overridden using environment variables.

---

Requirements

Required

• Python 3.13+
• Git
• Virtual Environment

---

Repository Dependencies

Clone the following repositories as siblings.

openHaus Net/

├── openhaus-mcp
├── openhaus-engineering-system
└── openhaus-portal

Without openhaus-engineering-system, repository indexing will be empty.

---

Optional Tools

• MCP Inspector
• Cursor
• Claude Desktop
• VS Code MCP integrations

---

Installation

Clone the repository.

git clone https://github.com/bluntsupremaci/openhaus-mcp.git

cd openhaus-mcp

Create a virtual environment.

python3 -m venv .venv

Activate it.

macOS/Linux

source .venv/bin/activate

Windows

.venv\Scripts\activate

Install dependencies.

pip install -e .

or

pip install -r requirements.txt

---

Configuring OHES

If the engineering repository is not a sibling:

export OHES_ROOT="/absolute/path/to/openhaus-engineering-system"

---

Verify Repository Paths

python -c "
from config import *

for name, path in [
    ('OHES', OHES_ROOT),
    ('DOCS', DOCS_ROOT),
    ('KNOWLEDGE', KNOWLEDGE_ROOT),
    ('PROJECT', PROJECT_ROOT)
]:
    print(f'{name}: {path} exists={path.exists()}')
"

---

Running the Server

source .venv/bin/activate

python server.py

A successful startup looks similar to:

Platform ready (documents=25, watcher=True)

---

Using MCP Inspector

Setting	Value
Transport	STDIO
Command	/path/to/openhaus-mcp/.venv/bin/python
Arguments	server.py

---

Development Workflow

Run formatting and static analysis before committing.

ruff check .

ruff format .

pyright

pytest

---

MCP Tool Categories

Project Tools

Tool	Purpose
get_project_manifest	Project manifest
get_project_status	Current status
get_project_readme	README
list_project_files	Markdown project files

---

Documentation Tools

Provides list/get operations for:

• Architecture
• Constitution
• Governance
• Organisation
• Standards
• Workflows

---

Knowledge Tools

Supports:

• ADRs
• Engineering Patterns
• Playbooks
• Reports
• Modules
• Checklists

---

Repository Intelligence

Tool	Description
list_repository_domains	Repository domains
list_repository_sections	Sections within domains
list_repository_documents	Repository documents
resolve_repository_document	Resolve exact identifier
search_repository	Hybrid search
search_repository_semantic	Semantic search
repository_related	Outgoing references
repository_referenced_by	Incoming references
repository_neighbours	Graph neighbours
repository_statistics	Repository statistics
refresh_repository	Full rebuild
plan_engineering_task	Context-aware engineering planning

---

Usage Tips

Searching

Search first.

adr

Then resolve using the returned identifier.

ADR-0001 — ADOPT DJANGO

---

Listing Documents

Leave the domain empty to list every indexed document.

---

Required Parameters

Inspector tools marked with:

identifier*

require a value.

Running them with empty parameters will produce validation errors.

---

Environment Variables

Variable	Description
OHES_ROOT	OHES repository
PROJECT_ROOT	OpenHaus project documentation
PORTAL_ROOT	Django application
REPOSITORY_ROOT	Filesystem root watched by RepositoryWatcher

---

Repository Structure

openhaus-mcp/

├── server.py
├── config.py
├── pyproject.toml
├── pytest.ini
│
├── services/
│
├── tools/
│
├── utils/
│
├── tests/
│
└── README.md

---

Troubleshooting

Problem	Cause	Solution
total_documents: 0	Incorrect OHES_ROOT	Verify repository path
Unable to resolve adr	Partial identifier	Search first, then resolve
Field required: identifier	Empty Inspector arguments	Supply identifier
Import failures during testing	Missing Python path	Add pythonpath = . to pytest.ini

---

Future Roadmap

Planned improvements include:

• Vector database support
• Pluggable embedding providers
• AI planning engine
• Repository caching
• Cross-project indexing
• Documentation generation
• Engineering analytics
• Multi-project workspaces
• Live repository events
• Agent orchestration support

---

Related Projects

• openhaus-mcp
• openhaus-engineering-system
• openhaus-portal

---

OpenHaus

OpenHaus is a campus internet access platform engineered using the OpenHaus Engineering System (OHES).

The MCP server serves as the AI gateway into that engineering ecosystem, enabling intelligent documentation retrieval, semantic search, repository understanding, and AI-assisted software engineering workflows.