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

Repository Ecosystem

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

Repository Responsibilities

Related MCP server: Obsidian MCP Server

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

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

Development Workflow

Run formatting and static analysis before committing.

ruff check .

ruff format .

pyright

pytest

MCP Tool Categories

Project Tools

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

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

Repository Structure

openhaus-mcp/

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

Troubleshooting

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.