OpenCompanyBrain MCP Server
by jeko1975
README.md
# OpenCompanyBrain
A local knowledge workspace for people and AI assistants.
Keep documents, source references, decisions and their revisions under your control.
Connect compatible assistants through MCP. Choose a local model or an optional
remote provider for tasks that need generation.
**M12 — reviewed browser refresh, folder imports and verified local snapshots.** The original wiki interface is the default
application: its layout, navigation, views and workflows are reused alongside the
new source and automation controls. See the [feature matrix](docs/FEATURES.md) for
verified boundaries and remaining work.
This is a functional alpha. The [global roadmap](docs/ROADMAP.md#from-functional-alpha-to-a-first-beta)
sets out the remaining first-beta criteria, including the full application
lifecycle, separate knowledge spaces and representative retrieval evaluation.
*The real application with synthetic knowledge. The procedural brain, galaxy,
atom and city views share the same published documents and Markdown links.*
| Galaxy | Atom | City |
| --- | --- | --- |
|  |  |  |
| Animated document workflow | Search in the dark knowledge view |
| --- | --- |
|  |  |
| Functional report colors | Context and automation controls |
| --- | --- |
|  |  |
These are application screenshots, not generated illustrations. See the
[visual guide](docs/VISUALS.md) for navigation and the distinction between a
declared workflow and observed execution.
Interface language is configurable in **Settings → General**: Italian is the
default; English, French, German and Spanish are also available. This changes UI
labels, not documents, source names or authored workflows. Public screenshots use
the English interface with synthetic examples.
## Settings and context retrieval
Configuration lives in ten thematic tabs in the original **Settings** page.
**Tool**, after Memories in navigation, keeps operational actions and their results.
Empty choices explain which source or connection is missing; retrieval agents
without a dedicated provider use the current chat assistant when supported.
See [settings and delegation](docs/SETTINGS.md) for permissions and effort limits.
Configured sources, models, Git policies, databases and monitoring checks have
lists with **Add** and **Edit** controls in their dedicated Settings tab. Monitor
editors show the options for heartbeat files, identified processes or log markers;
their changes remain a draft until the existing plan and separate approval.
Existing item editors also offer confirmed, [reversible removal](docs/ENTITY_REMOVAL.md).
Removing a source or connection preserves original files, published knowledge,
database contents and private credentials. Removed entries can be restored;
sources, Git policies and schedules return inactive. A busy source or a model
still referenced by a policy cannot be removed.
The database editor follows the selected driver. **Test connection** shows
account-visible tables and columns within explicit discovery limits, then you
select the columns Brain may read. New connections are read-only; optional writes
require an explicit enable switch, permitted operations and separate column
selection. Testing a connection or enabling its write controls grants no database
privilege. Concurrent edits require reloading the connection.
Database passwords use a private internal [vault](docs/VAULT.md). Optional
AES-256-GCM encryption derives its key from a passphrase; the application does not
persist that passphrase or key. Unlock applies to the running server's shared
vault instance. A restart locks it again, and an independent MCP or CLI process
remains locked. The default private-file mode uses operating-system permissions;
disabling encryption explicitly returns to that mode.
With user management enabled, opening Settings and changing configuration require
the current administrator's password confirmation, valid for five minutes and
bound to that account and login. This does not enable user management or grant
additional database-account permissions.
The header has one **Search** field. Its adjacent options icon opens a dialog for
text or semantic/text retrieval, relevant knowledge pages or an AI answer, engine,
model, authorized sources and context preloading. Submit Search to request an AI
answer; changing options or reloading results does not generate another answer.
Advanced actions retain the original edit-plan, confirmation and anomaly-report
flow. Provider and model configuration belongs in **Settings → Models and AI**.
**[Tool](docs/TOOL_UI.md)** contains source actions, jobs, reviews, queries and
separately approved operations. Duplicate configuration/status cards stay in
Settings. Its
operational data remains available without fetching protected configuration.
Search choices use a signed browser-session cookie. **Settings → General** stores
installation defaults separately, behind the administrator confirmation boundary.
The dialog can restore those defaults; a defaults change invalidates older browser
choices. Search options neither grant source access or remote consent nor change
MCP retrieval defaults. An unavailable or still-loading local semantic model
leaves retrieval using text; selecting it does not download a model.
The same dialog reveals the existing AI choices when an AI answer is selected.
Sources use one Add button, a type selector and an explanation of the selected flow.
The separate **Updates** section selects Local folder or Browser folder to refresh
an existing managed copy, preserving preview, confirmation and recovery.
*Alpha.20 Settings in the original English interface. The sole connection is
synthetic; no connection paths, database account details or passwords are shown.*
| Settings tabs | Context retrieval |
| --- | --- |
|  |  |
## M12: refresh an existing source from a browser folder
In **Settings → Sources → Updates → Browser folder**, choose an existing
managed source, select one folder and explicitly review how its paths are mapped.
Keep the selected folder name, or use only its contents. The preview shows received
and effective paths, source-filter exclusions and added/changed/removed/unchanged
files before a separate replacement approval. Source identity, publication policy,
permissions, calendars, curated knowledge and original-file history use the
existing M10 lifecycle. Upload, approval and document processing remain separate.
Recovery and temporary discard have their own approvals. See
[browser refresh](docs/BROWSER_REFRESH.md) and [M12](docs/M12.md).
| Exact paths, differences and separate approval | Original animated workflow renderer |
| --- | --- |
|  |  |
## M11: import a browser-selected folder with its hierarchy
In **Settings → Sources → Add source → Browser Folder**, deliberately select one
folder. The preview retains the top folder and each relative path, so two files
called `readme.md` in different subfolders remain separate. Review names, sizes,
hashes and destination, then separately approve the new managed source.
Directory and flat-file uploads share private staging limits, expiry and deliberate
discard. Empty directories are not transmitted. A supported browser directory picker
is required; existing flat-file uploads and server-side folder copies remain
available. No source refresh, archive extraction, model or worker starts from this
control. See [folder uploads](docs/DIRECTORY_UPLOADS.md) and [M11](docs/M11.md).
| Relative paths and separate approval in the original Brain page | Original animated workflow renderer |
| --- | --- |
|  |  |
## M10: refresh an imported source without losing its identity
Select an existing managed source and a new server-accessible folder in
**Settings → Sources → Updates → Local folder**.
Review the complete inventory and added/changed/removed/unchanged paths, then
approve the replacement separately. Source identity, permissions, calendars and
publication policy remain. Curated Markdown keeps its normal protection; removed
originals do not silently delete derived documents.
Verified staging, a source-specific transition fence and exact recovery protect
interrupted work. Superseded originals remain in a bounded owned history, included
with current originals in version-4 coherent backups. Preview preserves existing
profiles; the first approved refresh enables a version fence and requires stopping
older readers. No model, worker or automatic refresh starts. See
[refresh](docs/REFRESH.md) and [M10](docs/M10.md).
| Reviewed replacement in the original Brain page | Animated explanation in the original document renderer |
| --- | --- |
|  |  |
## M9: upload selected files with a separate approval
Select flat files in **Settings → Sources → Add source → Browser Files**. Receipt
copies their bytes into private temporary storage, then displays the exact
inventory for a separate approval. Approved uploads become the same verified local
snapshots as M8. Existing folder mappings and publication policies remain available.
Status, expiry, revision checks and explicit discard support interrupted work.
Discarding temporary files preserves a source already registered. New controls use
the existing five-language shell; no model, worker or external destination starts
from uploading. Read [browser uploads](docs/UPLOADS.md) and [M9](docs/M9.md) for
storage limits, server buffering and the exact acceptance boundary.
| Private upload review in the original Brain page | Animated document workflow in the original renderer |
| --- | --- |
|  |  |
## M8: choose a mapped folder or a managed local copy
Keep working with an external folder through the existing mapping, or preview and
explicitly import a snapshot into the Brain's private local archive. The preview
shows the selected files, sizes and hashes before copying. Imported knowledge
continues to work when the external original is disconnected; its source uses the
existing reviewed or automatic publication policy and M7 permissions.
Managed originals are included in coherent backups and relocated with their source
identities when restored to another home. Existing mapped folders keep their
previous behavior and need their own original-file backup. Copying neither starts
a model nor grants remote consent. Stop older processes before the first approved
import: managed homes use a version fence so older backup readers cannot silently
omit their originals. See [managed imports](docs/IMPORTS.md) and [M8](docs/M8.md).
| Managed imports in the original Brain shell | Animated explanation using the original workflow renderer |
| --- | --- |
|  |  |
## M7: local source permissions and scoped assistants
Optionally assign readable sources and database connections to the existing users.
Administrators retain workspace control; editors and readers consult their assigned
resources without operational write rights. An empty assignment exposes no data.
Create separately revocable, expiring MCP credentials with finite allowlists; each
request and continuation checks current authority before retrieval and before its
response is returned. Restricted retrieval cannot invoke a model or reranker.
Source permissions are off by default. Explicit activation uses a reviewed plan,
invalidates previous sessions and suspends the old global API token. The original
Settings page, five languages, knowledge views, animations, report colors and M2–M6
functions remain the baseline. Administrators can use a short-lived scoped handoff
for their explicitly authorized model requests; a scoped assistant gains no model,
Git, monitoring or deployment rights from that handoff.
This remains one local workspace on a trusted operating-system account. Read
[source permissions and credentials](docs/ACCESS.md) before activation, older-version
changes or restore. It does not provide tenant hosting, HTTP OAuth or OS isolation.
## M6: source calendars and recoverable work
Choose an interval or an explicit five-field calendar for each registered source.
Preview local and UTC occurrences before applying a revision-bound plan. IANA time
zones, skipped spring hours, repeated autumn hours and bounded missed-run policies
are explicit; a stopped worker cannot create an unlimited catch-up backlog.
Queue and schedule cursors commit together, and known temporary lease-renewal
errors receive bounded retries while expired or replaced claims remain invalid.
The calendar panel extends the original Brain page in all five interface languages.
Existing intervals, source publication policies, drawing views, severity colors and
animated workflows remain. Configuration starts no new service and grants no new
model, telemetry or deployment permission. See [M6 acceptance](docs/M6.md) and
[calendars and worker limits](docs/SCHEDULING.md).
| Source calendars in the original Brain page | Animated explanation in the original workflow view |
| --- | --- |
|  |  |
## M5: signed deployment with governed rollout and verified recovery
Publish explicitly signed artifacts, preview a revision-bound plan and approve a
pilot group before approving the remaining devices. Separately configured agents
pull work over authenticated HTTPS; locally authorized launchers verify the exact
running version and application health. Failed upgrades can restart and verify
the previous trusted version. Durable receipts distinguish delivery, adoption,
recovery and uncertain outcomes.
Deployment is optional and disabled by default. Installation starts no service,
opens no incoming device port and grants no deployment rights to telemetry or MCP
retrieval. The new controls reuse the original Brain page and all five interface
languages. See [M5 acceptance](docs/M5.md), [signatures](docs/SIGNED_RELEASES.md),
[agents](docs/DEPLOYMENT_AGENT.md) and [backup boundaries](docs/M5_BACKUP.md).
| Signed releases and actual device receipts | Animated explanation in the original workflow view |
| --- | --- |
|  |  |
## M4: optional local monitoring and persistent incidents
Monitor explicitly configured heartbeat files, one identified process or bounded
log-marker counters. Run the passive agent in the foreground only when needed;
installation starts no monitor or sender. Offline queues retain stable identities,
survive core backup/restore and quarantine revoked checks before delivery.
The original Issues page adds persistent incident states, notes, revision checks,
verification evidence and recurrence. Existing report feeds and dynamic colours
remain available. Agent settings use a preview and explicit application in the
original Brain page, without starting an agent. The process adapter is an optional
extra; file checks work with the base installation. See [M4 acceptance](docs/M4.md),
[monitoring](docs/MONITORING.md), [incidents](docs/INCIDENTS.md) and
[SDK/receiver operations](docs/OPERATIONS.md).
| Persistent incidents in the original Issues page | Explicit local monitor settings |
| --- | --- |
|  |  |
## M3: graph choices, governed Git and retrieval decisions
Choose built-in Python analysis, NetworkX or rustworkx. Optional engines have a
reviewed catalogue, explicit plans and private dependency environments. Graph
queries preserve source scope, revision evidence and incomplete/unknown states;
the original dependency views retain their labelled legacy alias correction.
Git is optional and disabled for writes by default. A mapped repository can use
its current branch, main or a dedicated review branch. Commit, remote fetch for
review and push are separate durable plans; they never stage unrelated work.
The document revision remains independent from a pending Git operation.
Optional local rules or a separately running Rizzo Flow service can reorder
ambiguous candidates. Known files and continuations stay direct; abstention keeps
the original results. Jev live access is unavailable. The reproducible synthetic
comparison distinguishes actual measurements, unavailable models and simulated
contract replay. See [M3 acceptance](docs/M3.md), [graphs](docs/GRAPHS.md),
[Git policies](docs/GIT.md) and [decision engines](docs/DECISION_ENGINES.md).
| Actual rustworkx path in the original interface | Persistent local Git plan after restart |
| --- | --- |
|  |  |
## M2: documents, media and assistants
M2 adds page/slide/sheet/time evidence, bounded local conversion workers, optional
OCR/transcription, sampled video frames and explicitly authorized vision providers.
Managed Codex/Claude setup provides preview, revision checks and restoration;
selective low-effort retrieval leaves the main assistant's effort unchanged.
HTTP providers can choose Chat Completions or Responses. See [M2 acceptance](docs/M2.md),
[media](docs/MEDIA.md), [client setup](docs/CLIENTS.md) and [LLM adapters](docs/LLM.md)
for exact limits and verification. Optional models and executables are never
silently downloaded. The original interface and dynamic report views remain the
application baseline.
## Quick start
Use Python 3.11 or newer and a virtual environment. The M2 verification record
separates the local installed tests, native tool/model checks and Windows/macOS/Linux
CI on Python 3.11/3.13. Three additional media jobs exercise actual decoded video
frames; source-database CI uses disposable PostgreSQL 17, MariaDB 11.4 and Firebird 5.
Optional OCR, speech models and subscription clients have separate requirements.
The extraction deadline correction is retained. Alpha.6 also corrects a macOS
observer-counting test; the alpha.4 and alpha.5 releases remain withheld. See the [verification record](docs/VERIFICATION.md)
and [releases](https://github.com/jeko1975/OpenCompanyBrain/releases) for exact
revisions, results and installable packages. From this checkout:
```sh
python -m venv .venv
# Activate .venv using the command for your shell.
python -m pip install -e .
python -m opencompanybrain --home ./brain-data plan
python -m opencompanybrain --home ./brain-data init
python -m opencompanybrain --home ./brain-data doctor
python -m opencompanybrain --home ./brain-data demo
python -m opencompanybrain --home ./brain-data serve
```
Open <http://127.0.0.1:8877>. The demo uses synthetic material. Choose a data directory
outside the checkout for a lasting installation. A model account or API key should
not be needed to inspect the local workspace and try the demo.
The home page opens the original dark knowledge universe. Switch between Brain,
Galaxy, Atom and City; click a document light to focus, double-click to read,
use the wheel to zoom and drag to rotate. The original sidebar, search, directional
map, code tree, question pages, model selection, preferences and optional user roles
remain in the same interface. Open **Brain** (`/brain`, also `/workspace`) for source,
review, job, database and event controls. Document pages retain full Markdown and
animated workflow bands or lanes.
For a richer **separate demo home**, use `demo --gallery` instead of `demo`: it creates
12 example sources, 96 published documents, 288 real links and 12 declared workflows.
It also enables isolated synthetic error/warning/data reports. Their changing states
drive the colors of document lights, map areas and code-tree branches. The gallery
makes no model calls and does not import personal documents or configuration.
For AI-assisted installation, start with [AGENTS.md](AGENTS.md),
[project-manifest.json](project-manifest.json) and the [installation guide](docs/INSTALL.md).
Run the installed CLI's `--help` before configuring additional commands.
## What the project is for
- Map explicitly selected sources rather than uploading a computer's contents.
- Keep source provenance and distinguish extracted, generated and curated knowledge.
- Prepare document changes with review, or publish validated changes automatically
according to each source's policy.
- Retrieve a bounded, attributable context package through MCP.
- Add conversion, graph and operational integrations as optional components.
Some integrations remain experimental or planned. See the
[feature matrix](docs/FEATURES.md) for the implementation status and
[roadmap](docs/ROADMAP.md) for the wider scope.
## Local by choice
The application and its data directory run on your machine. Selecting a cloud model
or remote database makes the relevant transfer an explicit configuration decision.
Local installation alone does not make a remote model private or offline.
See [security](SECURITY.md) and [configuration](docs/CONFIGURATION.md).
## Documentation
- [Install and verify](docs/INSTALL.md)
- [Original visual views and document workflows](docs/VISUALS.md)
- [Original interface and compatibility boundaries](docs/ORIGINAL_INTERFACE.md)
- [Retrieval and automation optimizations](docs/OPTIMIZATIONS.md)
- [Settings and context delegation](docs/SETTINGS.md)
- [Configuration and data](docs/CONFIGURATION.md)
- [Local source permissions and assistant credentials](docs/ACCESS.md)
- [Reviewed refresh and snapshot history](docs/REFRESH.md)
- [Optional database sources](docs/DATABASES.md)
- [Local document and media extraction](docs/MEDIA.md)
- [Optional telemetry and deployment](docs/OPERATIONS.md)
- [Signed releases, rollout and rollback](docs/M5.md)
- [Source calendars and recoverable work](docs/SCHEDULING.md)
- [Connect an assistant through MCP](docs/MCP.md)
- [Source and document lifecycle](docs/WORKFLOWS.md)
- [CLI reference](docs/CLI.md)
- [Feature status](docs/FEATURES.md)
- [Verification record](docs/VERIFICATION.md)
- [Publication gate](docs/PUBLICATIONGATE.md)
- [Roadmap](docs/ROADMAP.md)
- [Guida in italiano](docs/it/README.md)
- [Contribute](CONTRIBUTING.md) · [Changes](CHANGELOG.md) · [MIT license](LICENSE)
Screenshots are generated from synthetic demo data. A screenshot demonstrates a
particular view, not completion of every roadmap item.
This server cannot be deployed
Maintenance
ActivityNo data
ResponsivenessSyncing