Skip to content
Back to search

second-brain-core

Shared library for the Second Brain MCP servers: sign-in, audit log, HTTP serving and search by meaning.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/second-brain-tools--second-brain-core/badge.svg)](/listings/second-brain-tools--second-brain-core)

HTML

<a href="/listings/second-brain-tools--second-brain-core"><img src="/api/listings/second-brain-tools--second-brain-core/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 70 lines
  1. # second-brain-core
  2. The shared library of the Second Brain MCP servers:
  3. [second-brain-joplin](https://github.com/second-brain-tools/second-brain-joplin) (notes)
  4. and its sibling for mail. Each server talks to one store; everything they do the same
  5. way lives here, written and tested once.
  6. > **0.x: the interfaces may still change.** Each server pins a compatible range
  7. > (`second-brain-core>=0.1,<0.2`), and a change that breaks one is a new minor version.
  8. ## What it holds
  9. | Module | What it does |
  10. |---|---|
  11. | `server` | `Server`: how a server describes itself (its name, variable prefix, package, port). Every other piece takes it, so nothing here names a product. |
  12. | `env` | Where settings come from (the environment, then a named `--env-file` *or* a checkout's `.env`, never both), and readers that never raise. |
  13. | `auth` | GitHub sign-in for HTTP mode through FastMCP's OAuth proxy, limited to listed numeric GitHub ids. |
  14. | `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. |
  15. | `remote` | HTTP mode's options, the start-up guardrails, the transport choice (stdio unless asked), the middleware stack, and the run calls. |
  16. | `health` | The `/healthz` route: two booleans, 503 when the store is down. |
  17. | `failure` | The error a client sees: a planned failure's own sentence, or a fixed one for anything unplanned. |
  18. | `recent` | A short memory of what a write answered, so a repeated request writes nothing new. |
  19. | `annotations` | The tool annotations every server uses the same way. |
  20. | `testing` | Security regression checks each server runs against itself in its own CI. |
  21. | `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. |
  22. ## Using it in a server
  23. ```python
  24. # my_server/__init__.py: import the library first, and nothing that imports fastmcp.
  25. import second_brain_core # noqa: F401 (pins FastMCP's env file before fastmcp loads)
  26. # my_server/app.py
  27. from second_brain_core.server import Server
  28. SERVER = Server(name="my-server", prefix="SBM_", package="my_server", default_port=8777)
  29. ```
  30. **Importing `second_brain_core` must come before anything imports fastmcp.** FastMCP
  31. reads its own settings, the transport among them, from a `.env` in the working
  32. directory when it is first imported; importing this package stops that. Keep the
  33. server's `__init__.py` free of other imports, because import sorting would move a
  34. `fastmcp` import above it. `testing.check_dotenv_cannot_set_fastmcp` catches the
  35. mistake; run it in the server's suite.
  36. Then build the server with `remote.build_middleware(SERVER, ...)` and
  37. `mask_error_details=True`, end every tool with `failure.tool_error` for the failures
  38. it plans for and `failure.unexpected` for the rest, and serve with
  39. `remote.run_stdio` or `remote.run_http`.
  40. ## Search by meaning
  41. ```bash
  42. pip install "second-brain-core[semantic]" # sqlite-vec + FastEmbed (the default)
  43. pip install "second-brain-core[semantic,semantic-chroma]" # the Chroma store
  44. pip install "second-brain-core[semantic,semantic-st]" # sentence-transformers models
  45. ```
  46. A server re-exports these as its own extras. Each server keeps **its own index
  47. directory**: the index file records which server owns it and refuses another. The
  48. embedding runtime has no build for Python 3.15 yet, so the extra needs 3.11 to 3.14.
  49. ## Releasing
  50. The library is released **first**: a change a server needs is released here, then the
  51. server's pin moves to it. See [docs/releasing.md](docs/releasing.md).
  52. ## License
  53. GNU Affero General Public License, version 3 or later ([LICENSE](LICENSE)).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.