second-brain-core
The shared library of the Second Brain MCP servers: second-brain-joplin (notes) and its sibling for mail. Each server talks to one store; everything they do the same way lives here, written and tested once.
0.x: the interfaces may still change. Each server pins a compatible range (
second-brain-core>=0.2,<0.3), and a change that breaks one is a new minor version.
What it holds
| Module | What it does |
|---|---|
server |
Server: how a server describes itself (its name, variable prefix, package, port). Every other piece takes it, so nothing here names a product. |
env |
Where settings come from (the environment, then a named --env-file or a checkout's .env, never both), and readers that never raise. |
auth |
GitHub sign-in for HTTP mode through FastMCP's OAuth proxy, limited to listed numeric GitHub ids. |
audit |
One log line per tool call (tool, caller, client, outcome, duration; never arguments, results or tokens), the per-caller rate limit, and the logging set-up that keeps tokens and content out of the log. |
remote |
HTTP mode's options, the start-up guardrails, the transport choice (stdio unless asked), the middleware stack, and the run calls. |
health |
The /healthz route: two booleans, 503 when the store is down. |
failure |
The error a client sees: a planned failure's own sentence, or a fixed one for anything unplanned. |
recent |
A short memory of what a write answered, so a repeated request writes nothing new. |
annotations |
The tool annotations every server uses the same way. |
textclean |
Outside text made safe to hand to a model: invisible and bidirectional characters removed, HTML reduced to the text a reader sees (hidden text dropped), and outside_text_notice, the sentence an answer carrying such text puts first. |
testing |
Security regression checks each server runs against itself in its own CI, including check_no_invisible_characters over its own source. |
semantic |
The semantic extra: search by meaning, and by words, over a server's items. The server supplies a Source; the Engine keeps the index in step and searches it, returning only what the source says is visible now. Stores: sqlite-vec (the default, with an FTS5 word index) and Chroma. semantic.testing has in-memory stand-ins for tests. |
Using it in a server
# my_server/__init__.py: import the library first, and nothing that imports fastmcp.
import second_brain_core # noqa: F401 (pins FastMCP's env file before fastmcp loads)
# my_server/app.py
from second_brain_core.server import Server
SERVER = Server(name="my-server", prefix="SBM_", package="my_server", default_port=8777)
Importing second_brain_core must come before anything imports fastmcp. FastMCP
reads its own settings, the transport among them, from a .env in the working
directory when it is first imported; importing this package stops that. Keep the
server's __init__.py free of other imports, because import sorting would move a
fastmcp import above it. testing.check_dotenv_cannot_set_fastmcp catches the
mistake; run it in the server's suite.
Then build the server with remote.build_middleware(SERVER, ...) and
mask_error_details=True, end every tool with failure.tool_error for the failures
it plans for and failure.unexpected for the rest, and serve with
remote.run_stdio or remote.run_http.
Search by meaning
pip install "second-brain-core[semantic]" # sqlite-vec + FastEmbed (the default)
pip install "second-brain-core[semantic,semantic-chroma]" # the Chroma store
pip install "second-brain-core[semantic,semantic-st]" # sentence-transformers models
A server re-exports these as its own extras. Each server keeps its own index directory: the index file records which server owns it and refuses another. The embedding runtime has no build for Python 3.15 yet, so the extra needs 3.11 to 3.14.
Releasing
The library is released first: a change a server needs is released here, then the server's pin moves to it. See docs/releasing.md.
License
GNU Affero General Public License, version 3 or later (LICENSE).
Metadata
Release files for second-brain-core 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| second_brain_core-0.2.0.tar.gz | 457.3 kB | With provenance | Details for second_brain_core-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| second_brain_core-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for second_brain_core-0.2.0-py3-none-any.whl |
Total release size: 521.6 kB
Release files / second_brain_core-0.2.0.tar.gz
| Download URL | second_brain_core-0.2.0.tar.gz |
|---|---|
| Size | 457.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
36a0a05c7ebc4a1595e2cff88c52f8b5b77e533db5736db9b7d57f1d852b4b14
|
|
BLAKE2b-256 checksum How to use checksums |
20921b77277e1202ff06cbe27c37757079ae18f1b0a636f3c1e9f0d889f3ffad
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 22, 2026.
Transparency logRelease files / second_brain_core-0.2.0-py3-none-any.whl
| Download URL | second_brain_core-0.2.0-py3-none-any.whl |
|---|---|
| Size | 64.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
284c70f9bbb510870ebee5b6dfb9d9f6812c22a2e4882c3c3d656abdfab72143
|
|
BLAKE2b-256 checksum How to use checksums |
575872c9c4cf6edb3c0db132ed32353a0916a0b03e5678196ade059026e34b3c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 22, 2026.
Transparency logSecurity for second-brain-core 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for second_brain_core-0.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 22, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.