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.

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

Related Pages

Related topics: AI Agent Integration and Troubleshooting

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.

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.

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

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.

Related Pages

Related topics: Introduction and System Architecture

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.

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.

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

Related Pages

Related topics: Core Tools: Memory, Knowledge Graph, and Reasoning, Configuration, Running Modes, and Deployment

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-

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-

1. 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-

1. 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-

1. 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.

Doramagic Pitfall Log

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
• 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.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/Hebbrix/hebbrix-mcp

2. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/Hebbrix/hebbrix-mcp

3. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• 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.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/Hebbrix/hebbrix-mcp

4. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/Hebbrix/hebbrix-mcp

5. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/Hebbrix/hebbrix-mcp

6. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/Hebbrix/hebbrix-mcp

7. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/Hebbrix/hebbrix-mcp

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using hebbrix-mcp with real data or production workflows.

• v0.3.20 - github / github_release
• v0.3.19 - github / github_release
• v0.3.18 - github / github_release
• v0.3.17 - github / github_release
• v0.3.16 - github / github_release
• v0.3.15 - github / github_release
• v0.3.14 - github / github_release
• v0.3.13 - github / github_release
• v0.3.12 - github / github_release
• v0.3.11 - github / github_release
• Configuration risk requires verification - GitHub / issue