# 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

```text
                    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

```text
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:

```text
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.

```text
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.

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

cd openhaus-mcp
```

Create a virtual environment.

```bash
python3 -m venv .venv
```

Activate it.

### macOS/Linux

```bash
source .venv/bin/activate
```

### Windows

```powershell
.venv\Scripts\activate
```

Install dependencies.

```bash
pip install -e .
```

or

```bash
pip install -r requirements.txt
```

---

# Configuring OHES

If the engineering repository is not a sibling:

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

---

# Verify Repository Paths

```bash
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

```bash
source .venv/bin/activate

python server.py
```

A successful startup looks similar to:

```text
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.

```bash
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.

```text
adr
```

Then resolve using the returned identifier.

```text
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

```text
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.