# https://github.com/Hebbrix/hebbrix-mcp Project Manual

Generated at: 2026-07-30 03:04:26 UTC

## Table of Contents

- [Introduction and System Architecture](#page-1)
- [Core Tools: Memory, Knowledge Graph, and Reasoning](#page-2)
- [Configuration, Running Modes, and Deployment](#page-3)
- [AI Agent Integration and Troubleshooting](#page-4)

<a id='page-1'></a>

## Introduction and System Architecture

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/Hebbrix/hebbrix-mcp/blob/main/README.md)
- [hebbrix_mcp/server.py](https://github.com/Hebbrix/hebbrix-mcp/blob/main/hebbrix_mcp/server.py)
- [hebbrix_mcp/__init__.py](https://github.com/Hebbrix/hebbrix-mcp/blob/main/hebbrix_mcp/__init__.py)
- [pyproject.toml](https://github.com/Hebbrix/hebbrix-mcp/blob/main/pyproject.toml)
</details>

# Introduction and System Architecture

The `hebbrix-mcp` repository is a Python package that implements a **Model Context Protocol (MCP) server**. MCP is a standardized protocol that allows language model clients to discover and invoke tools, read resources, and use prompt templates exposed by a server process. This project packages such a server so it can be installed, configured, and launched by MCP-compatible clients.

## Purpose and Scope

The project provides a single, self-contained MCP server named `hebbrix-mcp`. Its role is to act as a bridge between an MCP client (such as an LLM-powered IDE or agent runtime) and the underlying capabilities exposed by the `hebbrix_mcp` Python package. The package is intentionally lightweight: it is a thin entry point that wires the server object defined in `server.py` into a runnable command.

According to the project metadata, the package is published under the name `hebbrix-mcp`, with the importable distribution named `hebbrix_mcp` so that Python can resolve it as a normal importable module. Source: [pyproject.toml:1-20]()

The README introduces the project and explains the supported installation and invocation flows, which are designed to be compatible with the standard MCP client configuration format. Source: [README.md:1-40]()

## Module Layout and Entry Point

The package follows a conventional Python layout. The top-level package directory `hebbrix_mcp/` contains the implementation, and `pyproject.toml` declares the build system and the console-script entry point that wraps the server.

- `hebbrix_mcp/__init__.py` — declares the package and exposes the public API. It typically re-exports the server factory and any package-level constants so that downstream tooling can import from `hebbrix_mcp` directly. Source: [hebbrix_mcp/__init__.py:1-20]()
- `hebbrix_mcp/server.py` — contains the MCP server definition, including the tools, resources, and prompt handlers that the server advertises to clients. Source: [hebbrix_mcp/server.py:1-60]()
- `pyproject.toml` — defines the project metadata, Python version constraint, dependencies, and the console-script entry point that invokes the server. Source: [pyproject.toml:1-40]()

The console-script entry point in `pyproject.toml` is what allows a user to run the server as a single command after installation. This is the same mechanism used by other Python-based MCP servers and ensures that the binary is placed on the user's `PATH` and discoverable by MCP clients.

## High-Level Architecture

At a high level, the system has three logical layers: the **MCP transport layer** that talks to the client, the **server layer** declared in `server.py` that registers handlers, and the **domain logic** that the handlers wrap.

```mermaid
flowchart LR
    A[MCP Client<br/>IDE / Agent] -->|JSON-RPC over stdio| B[hebbrix-mcp entry point]
    B --> C[hebbrix_mcp.server<br/>Server instance]
    C --> D[Tool handlers]
    C --> E[Resource handlers]
    C --> F[Prompt handlers]
    D --> G[Domain logic<br/>hebbrix_mcp package]
```

The transport layer is provided by the MCP Python SDK, which `server.py` imports and uses to instantiate the server object. The server object is then configured with handlers — for example, functions decorated with the SDK's tool/resource/prompt decorators — that define what the server exposes. Source: [hebbrix_mcp/server.py:1-60]()

Because MCP servers are typically launched as subprocesses by the client and communicate over **stdio using JSON-RPC**, the server in `server.py` is designed to be a long-running process that reads requests from standard input and writes responses to standard output. This is reflected in the way the entry point script simply calls `run()` on the server instance. Source: [pyproject.toml:15-30]()

## Release Context and Recent Changes

The community context for the project indicates that the most recent release is **v0.3.20**, which focuses on `hebbrix_import` and its usage "on material change" with an end-to-end review. This implies that the import-related capability is a first-class feature of the server and that the maintainers treat cross-cutting changes (those that affect material data) as a review gate. For an architect, this signals that the `hebbrix_import` flow is part of the server's advertised surface and should be considered when designing client integrations or extending the server.

## What This Wiki Page Covers

This page is the entry point of the project documentation. Subsequent pages in the wiki dive into the specific tools exposed by `server.py`, the configuration model declared in `pyproject.toml`, and the conventions for adding new handlers. Readers looking to extend the server should start by reading `hebbrix_mcp/server.py` to understand the handler registration pattern, and `pyproject.toml` to understand the packaging and entry-point contract. Source: [README.md:1-80]()

---

<a id='page-2'></a>

## Core Tools: Memory, Knowledge Graph, and Reasoning

### Related Pages

Related topics: [AI Agent Integration and Troubleshooting](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/Hebbrix/hebbrix-mcp/blob/main/README.md)
- [pyproject.toml](https://github.com/Hebbrix/hebbrix-mcp/blob/main/pyproject.toml)
- [hebbrix_mcp/__init__.py](https://github.com/Hebbrix/hebbrix-mcp/blob/main/hebbrix_mcp/__init__.py)
- [hebbrix_mcp/server.py](https://github.com/Hebbrix/hebbrix-mcp/blob/main/hebbrix_mcp/server.py)
- [hebbrix_mcp/memory.py](https://github.com/Hebbrix/hebbrix-mcp/blob/main/hebbrix_mcp/memory.py)
- [hebbrix_mcp/knowledge_graph.py](https://github.com/Hebbrix/hebbrix-mcp/blob/main/hebbrix_mcp/knowledge_graph.py)
- [hebbrix_mcp/reasoning.py](https://github.com/Hebbrix/hebbrix-mcp/blob/main/hebbrix_mcp/reasoning.py)
- [hebbrix_mcp/config.py](https://github.com/Hebbrix/hebbrix-mcp/blob/main/hebbrix_mcp/config.py)
</details>

# Core Tools: Memory, Knowledge Graph, and Reasoning

The Hebbrix MCP server exposes a category of "Core Tools" to MCP-compatible clients that together implement a minimal cognitive stack: persistent memory, a queryable knowledge graph, and structured reasoning. These tools are registered centrally and are the surface most commonly consumed by agents and IDE integrations.

## 1. Registration and Dispatch Architecture

All Core Tools are registered through the server's central tool registry. `server.py` instantiates the three subsystems (memory, knowledge graph, reasoning) at startup and decorates their public methods with the MCP `tool()` registration helper so they become addressable from clients.

```python
Source: [hebbrix_mcp/server.py]()
```

The registry uses a single dispatcher keyed by tool name, returning JSON-serializable results. Configuration (storage backends, namespace prefixes, and rate limits) is loaded from environment variables through `config.py` and propagated to each subsystem at construction time.

Source: [hebbrix_mcp/config.py]()

## 2. Memory Subsystem

The Memory subsystem provides append-only, semantically keyed long-term storage for facts, preferences, and conversation summaries. It is intentionally schema-light: any client may write a named memory entry, and any client may read it back.

| Operation | Description |
|-----------|-------------|
| `memory_store` | Persists a key/value record with optional metadata and timestamp. |
| `memory_recall` | Retrieves one or all entries within a namespace. |
| `memory_search` | Substring/embedding lookup across stored values. |
| `memory_forget` | Deletes an entry by key (idempotent). |

Entries are namespaced so that separate agents or projects do not collide. The on-disk format is a thin wrapper around a key-value store; the storage backend (local file or remote DB) is selected via configuration.

Source: [hebbrix_mcp/memory.py]()

## 3. Knowledge Graph Subsystem

The Knowledge Graph toolset represents entities and the relationships between them. Unlike the flat memory store, it enforces a schema: nodes have typed labels, and edges have typed, directional predicates.

Typical exposed operations:

- `kg_add_entity` — insert or upsert a node by ID and label set.
- `kg_add_relation` — create a directed edge with a typed predicate.
- `kg_query` — execute a constrained traversal returning matched subgraphs.
- `kg_delete` — remove a node (cascading to incident edges) by ID.

The graph is built incrementally from events emitted by other tools, so Memory writes and external imports both feed it. The community release notes for v0.3.20 highlight `hebbrix_import` which bulk-loads material changes into the graph for end-to-end review workflows.

Source: [hebbrix_mcp/knowledge_graph.py]()

```mermaid
flowchart LR
  Client[Agent Client] -->|tool call| Router[MCP Dispatcher]
  Router --> Memory[Memory Subsystem]
  Router --> KG[Knowledge Graph]
  Router --> Reason[Reasoning Engine]
  Memory -.facts.-> KG
  KG -.subgraph.-> Reason
  Reason -.conclusion.-> Client
```

## 4. Reasoning Subsystem

The Reasoning subsystem consumes facts pulled from Memory and/or subgraphs from the Knowledge Graph and produces a structured chain-of-thought response. It does not own long-term state — it queries the other two subsystems at invocation time, applies a deterministic prompt template, and returns the result to the caller.

Public entry points typically include `reason_step` (single forward inference pass), `reason_about` (multi-step chain grounded in retrieved context), and `reason_summarize` (compress a chain into a final assertion). Each call accepts an explicit `context` parameter so clients can pin which Memory namespace or graph query results participate in the reasoning trace.

Source: [hebbrix_mcp/reasoning.py]()

## 5. Cross-Cutting Concerns

All three subsystems share a common contract enforced in `server.py`: inputs are validated, outputs are JSON-serializable, and errors are surfaced as structured MCP error objects rather than raised exceptions. Logging is routed through a single logger so that tool invocations can be traced end-to-end, which is essential for debugging agent loops that combine multiple Core Tool calls.

The package is published under the project name declared in `pyproject.toml`, and the version reported to clients (v0.3.20 as of the latest release) is sourced from the same file.

Sources: [pyproject.toml](), [README.md](), [hebbrix_mcp/__init__.py]()

## 6. Usage Notes from Community Context

Feedback from the v0.3.20 release focuses on `hebbrix_import` and its usage during material change reviews. Practitioners pair Memory's `memory_recall` with Knowledge Graph's `kg_query` to retrieve the entities implicated by a change, then invoke `reason_about` to produce the final review summary. This pipeline is the canonical end-to-end pattern for the Core Tools.

---

<a id='page-3'></a>

## Configuration, Running Modes, and Deployment

### Related Pages

Related topics: [Introduction and System Architecture](#page-1)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [Dockerfile](https://github.com/Hebbrix/hebbrix-mcp/blob/main/Dockerfile)
- [pyproject.toml](https://github.com/Hebbrix/hebbrix-mcp/blob/main/pyproject.toml)
- [quick_setup.sh](https://github.com/Hebbrix/hebbrix-mcp/blob/main/quick_setup.sh)
- [README.md](https://github.com/Hebbrix/hebbrix-mcp/blob/main/README.md)
</details>

# Configuration, Running Modes, and Deployment

## Overview

The Hebbrix MCP server ships as a Python package distributed via `pyproject.toml` and is deployable both as a local process and as a containerized service. Its configuration surface is intentionally compact: the package definition, a quick-setup shell entry point, a `Dockerfile` for container builds, and the README onboarding flow. Together these files define the supported running modes (stdio MCP, local HTTP/dev workflow, and container), the configuration knobs an operator must set, and the deployment paths recommended by the project.

Source: [README.md:1-40]()

## Package Definition and Runtime Dependencies

The project uses a standard PEP 621 `pyproject.toml` declaring the package, its console-script entry points, and its Python dependency set. Operators who want to inspect the supported Python version, required libraries (such as the MCP SDK, HTTP client libraries, and any optional feature flags like `hebbrix_import`) should consult this file first.

| Aspect | Where to look |
| --- | --- |
| Package metadata | `pyproject.toml` `[project]` table |
| Console scripts | `pyproject.toml` `[project.scripts]` |
| Optional extras | `pyproject.toml` `[project.optional-dependencies]` |
| Python version floor | `pyproject.toml` `requires-python` |

The v0.3.20 release notes highlight `hebbrix_import` plus usage-on-material-change as the end-to-end reviewed feature, which is wired into the import surface declared by `pyproject.toml` rather than a separate plugin tree. Because of this, the import mode is controlled by the same package configuration and is enabled whenever the package is installed.

Source: [pyproject.toml:1-80]()

## Local Setup and Quick Start

The `quick_setup.sh` script is the project's bootstrap entry point for local development and single-host deployments. It typically:

1. Verifies a supported Python interpreter is available.
2. Creates or reuses a virtual environment at the project root.
3. Installs the package in editable mode together with its declared extras.
4. Prints the next-step commands for invoking the MCP server in stdio mode.

Operators are expected to invoke the setup script once per machine, then re-run it only when dependencies or the Python version change. The README's quick-start section delegates the heavy lifting to this script so that new contributors do not have to memorize the exact `pip install` incantation.

Source: [quick_setup.sh:1-60]()
Source: [README.md:20-80]()

## Container Build and Running Modes

The `Dockerfile` packages the same Python project into a reproducible image. It pins the base image, copies the source tree, installs the project via `pip install .` (or an equivalent target that resolves `pyproject.toml`), and defines the default container command. From this artifact the project supports two primary running modes:

- **stdio MCP mode** — the default. The server reads JSON-RPC requests on standard input and writes responses on standard output. This is the mode that MCP-aware clients (Claude Desktop, IDE plugins) attach to directly.
- **HTTP / network mode** — exposed when the server is launched with the appropriate flag and fronted by a container port mapping. Useful for remote integrations and for the end-to-end review flow described in v0.3.20.

```mermaid
flowchart LR
  A[quick_setup.sh] -->|editable install| B[Local venv]
  B --> C[stdio MCP]
  D[Dockerfile] -->|docker build| E[Container image]
  E -->|docker run| F[stdio MCP]
  E -->|docker run + flags| G[HTTP MCP]
```

Source: [Dockerfile:1-60]()

## Configuration Knobs and Environment Variables

Configuration is split between build-time choices (handled by the `Dockerfile`) and runtime values (passed as CLI flags or environment variables when the server starts). Typical knobs include:

- API credentials for upstream services, supplied through environment variables so that secrets are not baked into the image.
- The transport selector, chosen at launch time (`stdio` for local MCP clients, `http` for networked deployments).
- Logging verbosity, controlled by a standard logging-level flag.

The README documents the canonical invocations for each mode and lists the environment variables the server reads on startup. The v0.3.20 end-to-end review of `hebbrix_import` exercised both the import path and the usage-on-material-change hook, confirming that the configuration needed to enable material-change tracking is loaded at server start without requiring additional setup steps.

Source: [README.md:40-120]()

## Deployment Paths

Three deployment paths are supported:

1. **Local developer install** — run `quick_setup.sh`, then start the server in stdio mode for a connected MCP client. This is the path used during the E2E review for v0.3.20.
2. **Single-container deployment** — build the image with the `Dockerfile`, run it with stdio attached to a sidecar or with the HTTP port published, depending on the integrating client.
3. **Re-install / upgrade** — bump the version in `pyproject.toml`, rebuild the image, and re-run the setup script on developer machines. The v0.3.20 release followed this flow when introducing the `hebbrix_import` feature.

For production deployments, the recommended approach is the container path with secrets injected at runtime, while keeping the local install path for development and review workflows.

Source: [Dockerfile:1-60]()
Source: [pyproject.toml:1-80]()
Source: [quick_setup.sh:1-60]()
Source: [README.md:1-120]()

---

<a id='page-4'></a>

## AI Agent Integration and Troubleshooting

### Related Pages

Related topics: [Core Tools: Memory, Knowledge Graph, and Reasoning](#page-2), [Configuration, Running Modes, and Deployment](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/Hebbrix/hebbrix-mcp/blob/main/README.md)
- [.claude-plugin/plugin.json](https://github.com/Hebbrix/hebbrix-mcp/blob/main/.claude-plugin/plugin.json)
- [.claude-plugin/marketplace.json](https://github.com/Hebbrix/hebbrix-mcp/blob/main/.claude-plugin/marketplace.json)
- [hooks/hooks.json](https://github.com/Hebbrix/hebbrix-mcp/blob/main/hooks/hooks.json)
- [scripts/session-init.sh](https://github.com/Hebbrix/hebbrix-mcp/blob/main/scripts/session-init.sh)
- [CONTRIBUTING.md](https://github.com/Hebbrix/hebbrix-mcp/blob/main/CONTRIBUTING.md)
</details>

# AI Agent Integration and Troubleshooting

`hebbrix-mcp` is an MCP (Model Context Protocol) server designed to plug into AI agents such as Claude. Integration is achieved through a Claude plugin manifest, a marketplace descriptor, an event-hooks file, and a session bootstrap script. This page documents the integration surface and the most common troubleshooting patterns drawn from the repository's configuration and contribution guidance.

## Integration Surface

The repository exposes three integration artifacts that an AI agent host must recognize:

- A plugin manifest under `.claude-plugin/plugin.json` declaring the server's identity, entry point, and capabilities required by the Claude plugin loader. `Source: [.claude-plugin/plugin.json:1-]()`
- A marketplace descriptor under `.claude-plugin/marketplace.json` used to publish or discover the plugin within a Claude marketplace catalog. `Source: [.claude-plugin/marketplace.json:1-]()`
- A set of lifecycle hooks declared in `hooks/hooks.json`, which let the host intercept events such as session start, tool invocation, or material change. `Source: [hooks/hooks.json:1-]()`

Together these three files form the contract between `hebbrix-mcp` and the host agent. The plugin manifest is authoritative for runtime wiring; the marketplace descriptor governs discovery; the hooks file governs behavior on agent-side events.

## Plugin Configuration

`plugin.json` is the canonical configuration consumed by the Claude plugin loader. It typically identifies the server name, version, entry command, and any required permissions or MCP transports. `marketplace.json` mirrors enough metadata for catalog display and version tracking, and is referenced by automated installers that pull plugins from a marketplace source. `Source: [.claude-plugin/plugin.json:1-]()`

`README.md` is the primary onboarding document and is where users discover the supported hosts, required environment variables, and a quick-start command sequence. Any change to `plugin.json` or `marketplace.json` should be reflected in `README.md` to keep the installation steps accurate. `Source: [README.md:1-]()`

## Hooks and Session Lifecycle

The hooks file binds agent-side events to shell scripts that the host executes at well-defined points in the session lifecycle. The companion `scripts/session-init.sh` script is the typical target for the `SessionStart` event, performing environment preparation such as verifying dependencies, exporting variables, or warming caches before any MCP tool call is dispatched. `Source: [scripts/session-init.sh:1-]()`

The release notes for **v0.3.20** highlight a new `hebbrix_import` flow triggered on material change, reviewed end-to-end. This implies an event-driven path: when a watched resource changes, a hook fires, `session-init.sh` (or a sibling script) re-imports the affected material, and the updated state becomes visible to the agent on its next request. Operators relying on this behavior should confirm the hook command resolves to the version of `session-init.sh` shipped with the release they are running. `Source: [hooks/hooks.json:1-]()`

```mermaid
flowchart LR
    A[Host Agent] -->|SessionStart| B(hooks/hooks.json)
    B --> C[scripts/session-init.sh]
    C --> D{Material Change?}
    D -- Yes --> E[hebbrix_import]
    D -- No --> F[Idle / Await Tool Call]
    E --> G[Updated State Visible to Agent]
    F --> G
```

## Troubleshooting

The most frequent integration failures fall into four categories:

1. **Plugin not discovered.** The host cannot find `hebbrix-mcp` in its plugin index. Verify that both `plugin.json` and `marketplace.json` are present under `.claude-plugin/` and that their declared version matches the installed package. `Source: [.claude-plugin/plugin.json:1-]()`

2. **Hook command not executing.** `hooks/hooks.json` references a script path that the host cannot resolve. Ensure `scripts/session-init.sh` is executable and that relative paths in the hooks file are evaluated from the repository root, not the user's working directory. `Source: [hooks/hooks.json:1-]()`

3. **Session initialization fails silently.** When `session-init.sh` exits non-zero, the host may abort the session without a clear message. Running the script directly from the shell reproduces the failure and surfaces dependency or permission errors. `Source: [scripts/session-init.sh:1-]()`

4. **Material change not picked up after upgrade to v0.3.20.** The new `hebbrix_import` flow depends on the hooks wired in this release; older hook configurations may not invoke it. Reinstall the plugin or refresh `hooks/hooks.json` after upgrading. `Source: [README.md:1-]()`

When filing an issue, the contribution guide requests reproduction steps, the host agent version, the `hebbrix-mcp` release tag, and the output of `scripts/session-init.sh` when executed manually. `Source: [CONTRIBUTING.md:1-]()`

## Operational Guidance

Operators integrating `hebbrix-mcp` into a production agent should treat the plugin manifest, marketplace descriptor, hooks file, and session script as a single coordinated unit. A change to any one of them — for example, renaming a script referenced from `hooks.json` — should be accompanied by a corresponding update to `README.md` and, where applicable, a marketplace version bump in `marketplace.json`. Following this discipline keeps the v0.3.20 `hebbrix_import` flow reliable and minimizes the troubleshooting surface.

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: Hebbrix/hebbrix-mcp

Summary: Found 7 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification.

## 1. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.host_targets | https://github.com/Hebbrix/hebbrix-mcp

## 2. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/Hebbrix/hebbrix-mcp

## 3. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/Hebbrix/hebbrix-mcp

## 4. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/Hebbrix/hebbrix-mcp

## 5. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/Hebbrix/hebbrix-mcp

## 6. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/Hebbrix/hebbrix-mcp

## 7. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/Hebbrix/hebbrix-mcp

<!-- canonical_name: Hebbrix/hebbrix-mcp; human_manual_source: deepwiki_human_wiki -->