second-brain-core 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- second_brain_core/__init__.py +32 -0
- second_brain_core/annotations.py +15 -0
- second_brain_core/audit.py +275 -0
- second_brain_core/auth.py +235 -0
- second_brain_core/env.py +171 -0
- second_brain_core/errors.py +37 -0
- second_brain_core/failure.py +87 -0
- second_brain_core/health.py +48 -0
- second_brain_core/py.typed +0 -0
- second_brain_core/recent.py +69 -0
- second_brain_core/remote.py +252 -0
- second_brain_core/semantic/__init__.py +7 -0
- second_brain_core/semantic/chunking.py +48 -0
- second_brain_core/semantic/embedders.py +68 -0
- second_brain_core/semantic/engine.py +218 -0
- second_brain_core/semantic/stores.py +539 -0
- second_brain_core/semantic/sync.py +17 -0
- second_brain_core/semantic/testing.py +183 -0
- second_brain_core/semantic/types.py +130 -0
- second_brain_core/server.py +44 -0
- second_brain_core/testing.py +57 -0
- second_brain_core-0.1.0.dist-info/METADATA +106 -0
- second_brain_core-0.1.0.dist-info/RECORD +25 -0
- second_brain_core-0.1.0.dist-info/WHEEL +4 -0
- second_brain_core-0.1.0.dist-info/licenses/LICENSE +661 -0
second_brain_core/env.py
ADDED
|
@@ -0,0 +1,171 @@
|
|
|
1
|
+
"""Where a server's settings come from, and the readers that parse them.
|
|
2
|
+
|
|
3
|
+
**Where from.** The process environment first. Then either the env file named on the
|
|
4
|
+
command line (``--env-file``) or, failing that, the ``.env`` of the source checkout
|
|
5
|
+
the code runs from: never both. A named file is the whole configuration; a
|
|
6
|
+
checkout's ``.env`` would quietly fill in whatever the file leaves out. A variable
|
|
7
|
+
already set to something always wins over a file.
|
|
8
|
+
|
|
9
|
+
**How read.** The readers never raise. A value that can't be read gives ``None``
|
|
10
|
+
(or the reader's documented answer), the server keeps its default and records the
|
|
11
|
+
variable's name, and its commands refuse to start until the value is fixed. Raising
|
|
12
|
+
instead would break ``/healthz``, which reads the settings on every request.
|
|
13
|
+
"""
|
|
14
|
+
|
|
15
|
+
import os
|
|
16
|
+
import tomllib
|
|
17
|
+
from collections.abc import Mapping
|
|
18
|
+
from pathlib import Path
|
|
19
|
+
|
|
20
|
+
from dotenv import dotenv_values
|
|
21
|
+
|
|
22
|
+
from .errors import ServeConfigError
|
|
23
|
+
from .server import Server
|
|
24
|
+
|
|
25
|
+
_YES = frozenset({"1", "true", "yes", "on"})
|
|
26
|
+
_NO = frozenset({"0", "false", "no", "off"})
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
def apply_env(values: Mapping[str, str | None]) -> None:
|
|
30
|
+
"""Put ``values`` into the environment, keeping any variable already set to something.
|
|
31
|
+
|
|
32
|
+
A variable that is set to nothing doesn't count as set here. Otherwise an empty
|
|
33
|
+
filter variable exported by a shell or a service manager would silently beat the
|
|
34
|
+
filter written in the file.
|
|
35
|
+
"""
|
|
36
|
+
for name, value in values.items():
|
|
37
|
+
if value is not None and not os.environ.get(name):
|
|
38
|
+
os.environ[name] = value
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
def load_env_file(path: Path) -> None:
|
|
42
|
+
"""Load ``KEY=value`` lines from ``path`` into the environment, keeping set ones.
|
|
43
|
+
|
|
44
|
+
For service managers like launchd that can't load an env file themselves. A file
|
|
45
|
+
that is missing or unreadable is an error, not a silent no-op.
|
|
46
|
+
"""
|
|
47
|
+
if not path.is_file():
|
|
48
|
+
raise ServeConfigError(f"--env-file {path} does not exist or is not a file")
|
|
49
|
+
apply_env(dotenv_values(path))
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
def checkout_env_file(server: Server, package_dir: Path | None = None) -> Path | None:
|
|
53
|
+
"""The ``.env`` of the source checkout ``server`` runs from, or None.
|
|
54
|
+
|
|
55
|
+
``.env`` is a development convenience, so it is looked for in exactly one place:
|
|
56
|
+
beside the project's own ``pyproject.toml``, two levels above the package
|
|
57
|
+
(``<checkout>/src/<package>``). An installed copy sits in ``site-packages`` with
|
|
58
|
+
no such file there, so it reads no ``.env`` at all: not one in a directory above
|
|
59
|
+
where it is installed (``~/.env`` for a tool installed under the home directory),
|
|
60
|
+
and never the working directory's, which is whatever project the MCP client has
|
|
61
|
+
open. A ``.env`` can point a server at another store or widen what it shows, so
|
|
62
|
+
only a file the operator chose may do that.
|
|
63
|
+
"""
|
|
64
|
+
here = server.package_dir() if package_dir is None else package_dir
|
|
65
|
+
if here is None:
|
|
66
|
+
return None
|
|
67
|
+
root = here.parent.parent
|
|
68
|
+
try:
|
|
69
|
+
with (root / "pyproject.toml").open("rb") as handle:
|
|
70
|
+
project = tomllib.load(handle).get("project")
|
|
71
|
+
except (OSError, ValueError): # no such file, or not TOML: not a checkout
|
|
72
|
+
return None
|
|
73
|
+
if not isinstance(project, dict) or project.get("name") != server.name:
|
|
74
|
+
return None
|
|
75
|
+
env_file = root / ".env"
|
|
76
|
+
return env_file if env_file.is_file() else None
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
def load_dotenv(server: Server, package_dir: Path | None = None) -> None:
|
|
80
|
+
"""Load a source checkout's ``.env`` by the same rule as an env file; else nothing."""
|
|
81
|
+
path = checkout_env_file(server, package_dir)
|
|
82
|
+
if path is not None:
|
|
83
|
+
apply_env(dotenv_values(path))
|
|
84
|
+
|
|
85
|
+
|
|
86
|
+
def load_configuration(
|
|
87
|
+
server: Server, env_file: Path | None, *, package_dir: Path | None = None
|
|
88
|
+
) -> None:
|
|
89
|
+
"""Load the named env file, or else a checkout's ``.env``: one, never both."""
|
|
90
|
+
if env_file is not None:
|
|
91
|
+
load_env_file(env_file)
|
|
92
|
+
else:
|
|
93
|
+
load_dotenv(server, package_dir)
|
|
94
|
+
|
|
95
|
+
|
|
96
|
+
def env_bool(name: str, default: bool) -> bool:
|
|
97
|
+
"""A yes, or anything else for no; the default when unset."""
|
|
98
|
+
raw = os.environ.get(name)
|
|
99
|
+
if raw is None:
|
|
100
|
+
return default
|
|
101
|
+
return raw.strip().lower() in _YES
|
|
102
|
+
|
|
103
|
+
|
|
104
|
+
def env_switch(name: str) -> bool | None:
|
|
105
|
+
"""A protection that is on unless it is plainly switched off: True, False or None.
|
|
106
|
+
|
|
107
|
+
Unset, or set to nothing, is on. Only a plain no is off. Anything else (a typo)
|
|
108
|
+
is None: the caller keeps the protection on, and its commands refuse to start,
|
|
109
|
+
so a misspelt value can pass for neither answer.
|
|
110
|
+
"""
|
|
111
|
+
word = os.environ.get(name, "").strip().lower()
|
|
112
|
+
if not word or word in _YES:
|
|
113
|
+
return True
|
|
114
|
+
if word in _NO:
|
|
115
|
+
return False
|
|
116
|
+
return None
|
|
117
|
+
|
|
118
|
+
|
|
119
|
+
def env_flag(name: str) -> bool | None:
|
|
120
|
+
"""A power that is off unless it plainly says yes: True, False or None for a typo.
|
|
121
|
+
|
|
122
|
+
The opposite default of :func:`env_switch`, for something that stays off until
|
|
123
|
+
the operator asks for it.
|
|
124
|
+
"""
|
|
125
|
+
word = os.environ.get(name, "").strip().lower()
|
|
126
|
+
if not word or word in _NO:
|
|
127
|
+
return False
|
|
128
|
+
if word in _YES:
|
|
129
|
+
return True
|
|
130
|
+
return None
|
|
131
|
+
|
|
132
|
+
|
|
133
|
+
def env_list(name: str) -> tuple[str, ...]:
|
|
134
|
+
"""A comma-separated variable as its entries, trimmed, without empty ones."""
|
|
135
|
+
return tuple(entry.strip() for entry in os.environ.get(name, "").split(",") if entry.strip())
|
|
136
|
+
|
|
137
|
+
|
|
138
|
+
def set_but_blank(*names: str) -> tuple[str, ...]:
|
|
139
|
+
"""Those of ``names`` that are in the environment and list nothing."""
|
|
140
|
+
return tuple(name for name in names if name in os.environ and not env_list(name))
|
|
141
|
+
|
|
142
|
+
|
|
143
|
+
def env_int(name: str, default: int, *, minimum: int, maximum: int | None = None) -> int | None:
|
|
144
|
+
"""A whole number from ``minimum`` to ``maximum``: the default when unset or empty.
|
|
145
|
+
|
|
146
|
+
None when the value isn't a whole number in that range.
|
|
147
|
+
"""
|
|
148
|
+
raw = os.environ.get(name, "").strip()
|
|
149
|
+
if not raw:
|
|
150
|
+
return default
|
|
151
|
+
try:
|
|
152
|
+
value = int(raw)
|
|
153
|
+
except ValueError:
|
|
154
|
+
return None
|
|
155
|
+
if value < minimum or (maximum is not None and value > maximum):
|
|
156
|
+
return None
|
|
157
|
+
return value
|
|
158
|
+
|
|
159
|
+
|
|
160
|
+
def env_seconds(name: str, default: float) -> float | None:
|
|
161
|
+
"""A positive, finite number of seconds: the default when unset or empty; else None."""
|
|
162
|
+
raw = os.environ.get(name, "").strip()
|
|
163
|
+
if not raw:
|
|
164
|
+
return default
|
|
165
|
+
try:
|
|
166
|
+
value = float(raw)
|
|
167
|
+
except ValueError:
|
|
168
|
+
return None
|
|
169
|
+
if not value > 0 or value == float("inf"): # also catches nan
|
|
170
|
+
return None
|
|
171
|
+
return value
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
"""The errors the shared pieces raise."""
|
|
2
|
+
|
|
3
|
+
|
|
4
|
+
class ServeConfigError(Exception):
|
|
5
|
+
"""A server was asked for a configuration it refuses to start with."""
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
class FilterError(Exception):
|
|
9
|
+
"""A server's filter setting names something its store doesn't have.
|
|
10
|
+
|
|
11
|
+
The tools it governs refuse while this holds: a filter that can't be resolved
|
|
12
|
+
must not fall back to showing everything. ``str()`` is the same fixed sentence
|
|
13
|
+
every time (``MESSAGE``) and is safe to hand to a remote client. ``detail`` says
|
|
14
|
+
which variable and entry is wrong; an entry can be the name of something the
|
|
15
|
+
operator wants hidden, so the detail is for the operator only (the log, the
|
|
16
|
+
command line). Each server subclasses it, setting ``MESSAGE`` and ``WHAT``.
|
|
17
|
+
"""
|
|
18
|
+
|
|
19
|
+
MESSAGE = "The server's filter settings don't match its store. Its log says which."
|
|
20
|
+
WHAT = "filter" # what the log line calls it: "the notebook filter doesn't resolve"
|
|
21
|
+
|
|
22
|
+
def __init__(self, detail: str) -> None:
|
|
23
|
+
super().__init__(self.MESSAGE)
|
|
24
|
+
self.detail = detail
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
class SemanticUnavailableError(Exception):
|
|
28
|
+
"""Search by meaning can't run: an optional dependency is missing, or the index
|
|
29
|
+
can't be used (it belongs to another server, say). The message says what to do."""
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
class IndexOwnedElsewhereError(SemanticUnavailableError):
|
|
33
|
+
"""The index directory holds another server's index: each server needs its own."""
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
class WordSearchUnavailableError(SemanticUnavailableError):
|
|
37
|
+
"""The index has no word search: the Chroma store, or a SQLite without FTS5."""
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
"""Turning a failure inside a tool into the error an MCP client sees.
|
|
2
|
+
|
|
3
|
+
Every tool ends the same way: a failure the server planned for becomes a
|
|
4
|
+
``ToolError`` with its own sentence (:func:`tool_error`), and anything else becomes
|
|
5
|
+
a ``ToolError`` with a fixed one (:func:`unexpected`). Build the server with
|
|
6
|
+
``mask_error_details=True`` as well, so an exception that escapes a tool anyway
|
|
7
|
+
reaches the client as FastMCP's generic sentence, never as its own text.
|
|
8
|
+
"""
|
|
9
|
+
|
|
10
|
+
import functools
|
|
11
|
+
import traceback
|
|
12
|
+
from collections.abc import Awaitable, Callable
|
|
13
|
+
from pathlib import Path
|
|
14
|
+
from typing import ParamSpec, TypeVar
|
|
15
|
+
|
|
16
|
+
from fastmcp.exceptions import ToolError
|
|
17
|
+
|
|
18
|
+
from .errors import FilterError
|
|
19
|
+
from .server import Server
|
|
20
|
+
|
|
21
|
+
P = ParamSpec("P")
|
|
22
|
+
R = TypeVar("R")
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
def tool_error(server: Server, exc: Exception) -> ToolError:
|
|
26
|
+
"""The ``ToolError`` for a planned failure, carrying its message to the client.
|
|
27
|
+
|
|
28
|
+
A filter that doesn't resolve also gets a log line with the detail. The client
|
|
29
|
+
is told only that the filter is wrong: the detail can name something the
|
|
30
|
+
operator wants hidden.
|
|
31
|
+
"""
|
|
32
|
+
if isinstance(exc, FilterError):
|
|
33
|
+
server.logger("tools").warning("the %s doesn't resolve: %s", exc.WHAT, exc.detail)
|
|
34
|
+
return ToolError(str(exc))
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
def internal_message(server: Server) -> str:
|
|
38
|
+
"""The sentence a client gets for a failure nobody planned for."""
|
|
39
|
+
return f"{server.name} couldn't complete this request. The server's log says where."
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
def unexpected(server: Server, tool: str, exc: BaseException) -> ToolError:
|
|
43
|
+
"""The ``ToolError`` for a failure nobody planned for, with a fixed sentence.
|
|
44
|
+
|
|
45
|
+
An exception's own text can hold what was being processed when it was raised:
|
|
46
|
+
a note's text, a header, a URL with a token in it. So neither the client nor the
|
|
47
|
+
log gets it. The log gets the exception's type and the place in the server's
|
|
48
|
+
package where it surfaced, which is what a fix needs.
|
|
49
|
+
"""
|
|
50
|
+
where = "outside the server's package"
|
|
51
|
+
package_dir = server.package_dir()
|
|
52
|
+
if package_dir is not None:
|
|
53
|
+
for frame in reversed(traceback.extract_tb(exc.__traceback__)):
|
|
54
|
+
path = Path(frame.filename).resolve()
|
|
55
|
+
if package_dir in path.parents:
|
|
56
|
+
where = f"{path.relative_to(package_dir)}:{frame.lineno} in {frame.name}"
|
|
57
|
+
break
|
|
58
|
+
server.logger("tools").error("unexpected %s in %s at %s", type(exc).__name__, tool, where)
|
|
59
|
+
return ToolError(internal_message(server))
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
def guarded(
|
|
63
|
+
server: Server,
|
|
64
|
+
) -> Callable[[Callable[P, Awaitable[R]]], Callable[P, Awaitable[R]]]:
|
|
65
|
+
"""A tool decorator: a ``ToolError`` passes through; anything else is :func:`unexpected`.
|
|
66
|
+
|
|
67
|
+
Put it under ``@mcp.tool``, so the tool keeps its own handling of the failures
|
|
68
|
+
it plans for and nothing else escapes it::
|
|
69
|
+
|
|
70
|
+
@mcp.tool(annotations=READ_ONLY)
|
|
71
|
+
@guarded(SERVER)
|
|
72
|
+
async def my_tool(...) -> ...: ...
|
|
73
|
+
"""
|
|
74
|
+
|
|
75
|
+
def decorate(tool: Callable[P, Awaitable[R]]) -> Callable[P, Awaitable[R]]:
|
|
76
|
+
@functools.wraps(tool)
|
|
77
|
+
async def run(*args: P.args, **kwargs: P.kwargs) -> R:
|
|
78
|
+
try:
|
|
79
|
+
return await tool(*args, **kwargs)
|
|
80
|
+
except ToolError:
|
|
81
|
+
raise
|
|
82
|
+
except Exception as exc:
|
|
83
|
+
raise unexpected(server, tool.__name__, exc) from None
|
|
84
|
+
|
|
85
|
+
return run
|
|
86
|
+
|
|
87
|
+
return decorate
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
"""The ``/healthz`` route both servers expose in HTTP mode."""
|
|
2
|
+
|
|
3
|
+
import asyncio
|
|
4
|
+
import time
|
|
5
|
+
from collections.abc import Awaitable, Callable
|
|
6
|
+
|
|
7
|
+
from starlette.requests import Request
|
|
8
|
+
from starlette.responses import JSONResponse
|
|
9
|
+
|
|
10
|
+
Probe = Callable[[], Awaitable[bool]]
|
|
11
|
+
Route = Callable[[Request], Awaitable[JSONResponse]]
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
def make_healthz(probe: Probe, key: str, *, cache_seconds: float = 0.0) -> Route:
|
|
15
|
+
"""A ``/healthz`` route: ``{"server": true, <key>: <probe's answer>}``.
|
|
16
|
+
|
|
17
|
+
HTTP mode only (stdio has no routes). It is never behind sign-in, since FastMCP
|
|
18
|
+
does not guard custom routes, so it reveals nothing about the store, no version
|
|
19
|
+
and no configuration: two booleans. 503 when the probe says no, so a monitor
|
|
20
|
+
sees it.
|
|
21
|
+
|
|
22
|
+
``probe`` answers whether the store behind the server answers. It must not
|
|
23
|
+
raise for a store that is down; if it does anyway, the answer is no. With
|
|
24
|
+
``cache_seconds`` above 0 one answer is reused that long, for a probe that is
|
|
25
|
+
costly (one that signs in, say); 0 asks every time.
|
|
26
|
+
"""
|
|
27
|
+
last: dict[str, float | bool] = {}
|
|
28
|
+
lock = asyncio.Lock()
|
|
29
|
+
|
|
30
|
+
async def ask() -> bool:
|
|
31
|
+
try:
|
|
32
|
+
return bool(await probe())
|
|
33
|
+
except Exception:
|
|
34
|
+
return False
|
|
35
|
+
|
|
36
|
+
async def healthz(_request: Request) -> JSONResponse:
|
|
37
|
+
if cache_seconds <= 0:
|
|
38
|
+
answer = await ask()
|
|
39
|
+
else:
|
|
40
|
+
async with lock:
|
|
41
|
+
now = time.monotonic()
|
|
42
|
+
if "at" not in last or now - float(last["at"]) > cache_seconds:
|
|
43
|
+
last["answer"] = await ask()
|
|
44
|
+
last["at"] = time.monotonic()
|
|
45
|
+
answer = bool(last["answer"])
|
|
46
|
+
return JSONResponse({"server": True, key: answer}, status_code=200 if answer else 503)
|
|
47
|
+
|
|
48
|
+
return healthz
|
|
File without changes
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
"""A short memory of what a tool that writes answered, so a repeat writes nothing new.
|
|
2
|
+
|
|
3
|
+
A write is made by one request, and requests get repeated: a client that timed
|
|
4
|
+
out sends the call again, a model that saw an error tries once more. Without a
|
|
5
|
+
memory, each repeat is a second write. So a tool that writes remembers, for a few
|
|
6
|
+
minutes, what it answered for a request (by the request's digest), and gives that
|
|
7
|
+
answer to the repeat.
|
|
8
|
+
|
|
9
|
+
Kept in memory only and never written anywhere: it should hold digests and ids,
|
|
10
|
+
not content, and it is fine to lose on a restart.
|
|
11
|
+
"""
|
|
12
|
+
|
|
13
|
+
import hashlib
|
|
14
|
+
import time
|
|
15
|
+
from collections import OrderedDict
|
|
16
|
+
from collections.abc import Callable
|
|
17
|
+
from typing import Generic, TypeVar
|
|
18
|
+
|
|
19
|
+
T = TypeVar("T")
|
|
20
|
+
|
|
21
|
+
REMEMBER_SECONDS = 600.0
|
|
22
|
+
REMEMBER_AT_MOST = 256
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
class Recent(Generic[T]):
|
|
26
|
+
"""What was answered for a request, for the last few minutes, by the request's digest."""
|
|
27
|
+
|
|
28
|
+
def __init__(
|
|
29
|
+
self,
|
|
30
|
+
seconds: float = REMEMBER_SECONDS,
|
|
31
|
+
at_most: int = REMEMBER_AT_MOST,
|
|
32
|
+
clock: Callable[[], float] = time.monotonic,
|
|
33
|
+
) -> None:
|
|
34
|
+
self._seconds = seconds
|
|
35
|
+
self._at_most = at_most
|
|
36
|
+
self._clock = clock
|
|
37
|
+
self._sent: OrderedDict[str, tuple[T, float]] = OrderedDict()
|
|
38
|
+
|
|
39
|
+
def get(self, key: str) -> T | None:
|
|
40
|
+
"""What was remembered for this request, if recently enough."""
|
|
41
|
+
entry = self._sent.get(key)
|
|
42
|
+
if entry is None:
|
|
43
|
+
return None
|
|
44
|
+
value, at = entry
|
|
45
|
+
if self._clock() - at > self._seconds:
|
|
46
|
+
del self._sent[key]
|
|
47
|
+
return None
|
|
48
|
+
return value
|
|
49
|
+
|
|
50
|
+
def put(self, key: str, value: T) -> None:
|
|
51
|
+
"""Remember ``value`` for this request, forgetting the oldest if full."""
|
|
52
|
+
self._sent.pop(key, None)
|
|
53
|
+
self._sent[key] = (value, self._clock())
|
|
54
|
+
while len(self._sent) > self._at_most:
|
|
55
|
+
self._sent.popitem(last=False)
|
|
56
|
+
|
|
57
|
+
def forget(self, key: str) -> None:
|
|
58
|
+
"""Drop a request whose answer turned out not to stand."""
|
|
59
|
+
self._sent.pop(key, None)
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
def request_key(*parts: str) -> str:
|
|
63
|
+
"""A digest of a request's parts, the same for the same request."""
|
|
64
|
+
digest = hashlib.sha256()
|
|
65
|
+
for part in parts:
|
|
66
|
+
encoded = part.encode()
|
|
67
|
+
digest.update(len(encoded).to_bytes(8, "big"))
|
|
68
|
+
digest.update(encoded)
|
|
69
|
+
return digest.hexdigest()
|
|
@@ -0,0 +1,252 @@
|
|
|
1
|
+
"""Streamable HTTP mode for ``serve``: options, start-up guardrails, the middleware and the run.
|
|
2
|
+
|
|
3
|
+
stdio stays the default. HTTP mode exists so a Claude custom connector, which calls
|
|
4
|
+
MCP servers from Anthropic's cloud, can reach this server through a tunnel. The
|
|
5
|
+
server itself binds to loopback by default; the tunnel (or a reverse proxy) is what
|
|
6
|
+
publishes it, under the public URL that sign-in needs as its base URL.
|
|
7
|
+
|
|
8
|
+
HTTP mode is **stateless with plain JSON responses**: every request stands alone,
|
|
9
|
+
so a restart never breaks a client's session, and no idle event stream is held
|
|
10
|
+
open for a proxy to cut. None of the tools sends server-initiated messages, which
|
|
11
|
+
is the only thing a stateful session would add.
|
|
12
|
+
"""
|
|
13
|
+
|
|
14
|
+
import ipaddress
|
|
15
|
+
import os
|
|
16
|
+
from collections.abc import Mapping, Sequence
|
|
17
|
+
from dataclasses import dataclass
|
|
18
|
+
from typing import Any
|
|
19
|
+
from urllib.parse import urlsplit
|
|
20
|
+
|
|
21
|
+
from fastmcp import FastMCP
|
|
22
|
+
from fastmcp.server.middleware import AuthMiddleware, Middleware
|
|
23
|
+
|
|
24
|
+
from .audit import AuditMiddleware, ClientNames, RegisteredClients, rate_limit
|
|
25
|
+
from .auth import allowlist_check
|
|
26
|
+
from .errors import ServeConfigError
|
|
27
|
+
from .server import Server
|
|
28
|
+
|
|
29
|
+
TRANSPORTS = ("stdio", "http")
|
|
30
|
+
DEFAULT_HOST = "127.0.0.1"
|
|
31
|
+
DEFAULT_PATH = "/mcp"
|
|
32
|
+
# Tool calls per minute per caller (a token bucket that allows bursts of half).
|
|
33
|
+
DEFAULT_RATE_LIMIT = 60
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
@dataclass(frozen=True)
|
|
37
|
+
class HttpOptions:
|
|
38
|
+
"""Where and how the HTTP transport listens."""
|
|
39
|
+
|
|
40
|
+
host: str
|
|
41
|
+
port: int
|
|
42
|
+
path: str = DEFAULT_PATH
|
|
43
|
+
public_url: str | None = None
|
|
44
|
+
no_auth: bool = False
|
|
45
|
+
rate_limit_per_minute: int = DEFAULT_RATE_LIMIT
|
|
46
|
+
|
|
47
|
+
@property
|
|
48
|
+
def public_host(self) -> str | None:
|
|
49
|
+
"""The host name of ``public_url`` (``notes.example.com``), if one is set."""
|
|
50
|
+
if not self.public_url:
|
|
51
|
+
return None
|
|
52
|
+
return urlsplit(self.public_url).hostname
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
def is_loopback(host: str) -> bool:
|
|
56
|
+
"""Return True if ``host`` only ever answers on this machine."""
|
|
57
|
+
if host.lower() == "localhost":
|
|
58
|
+
return True
|
|
59
|
+
try:
|
|
60
|
+
return ipaddress.ip_address(host.strip("[]")).is_loopback
|
|
61
|
+
except ValueError:
|
|
62
|
+
return False
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
def env_number(environ: Mapping[str, str], name: str) -> int | None:
|
|
66
|
+
"""A whole-number option from ``environ``; None when unset; refused when not a number.
|
|
67
|
+
|
|
68
|
+
HTTP options are read once, at start-up, so a bad one is refused here.
|
|
69
|
+
"""
|
|
70
|
+
raw = environ.get(name)
|
|
71
|
+
if raw is None or raw == "":
|
|
72
|
+
return None
|
|
73
|
+
try:
|
|
74
|
+
return int(raw)
|
|
75
|
+
except ValueError:
|
|
76
|
+
raise ServeConfigError(f"{name} must be a number, got {raw!r}") from None
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
def http_options(
|
|
80
|
+
server: Server,
|
|
81
|
+
*,
|
|
82
|
+
host: str | None = None,
|
|
83
|
+
port: int | None = None,
|
|
84
|
+
path: str | None = None,
|
|
85
|
+
public_url: str | None = None,
|
|
86
|
+
no_auth: bool = False,
|
|
87
|
+
environ: Mapping[str, str] | None = None,
|
|
88
|
+
) -> HttpOptions:
|
|
89
|
+
"""Build :class:`HttpOptions` from command-line values, falling back to the server's variables.
|
|
90
|
+
|
|
91
|
+
A flag wins over its environment variable, which wins over the default.
|
|
92
|
+
``--no-auth`` has no environment variable on purpose: switching sign-in off
|
|
93
|
+
must be visible on the command line.
|
|
94
|
+
"""
|
|
95
|
+
env = os.environ if environ is None else environ
|
|
96
|
+
env_port = env_number(env, server.var("PORT"))
|
|
97
|
+
env_rate = env_number(env, server.var("RATE_LIMIT_PER_MINUTE"))
|
|
98
|
+
if port is None:
|
|
99
|
+
port = env_port if env_port is not None else server.default_port
|
|
100
|
+
return HttpOptions(
|
|
101
|
+
host=host or env.get(server.var("HOST")) or DEFAULT_HOST,
|
|
102
|
+
port=port,
|
|
103
|
+
path=path or env.get(server.var("HTTP_PATH")) or DEFAULT_PATH,
|
|
104
|
+
public_url=(public_url or env.get(server.var("PUBLIC_URL")) or None),
|
|
105
|
+
no_auth=no_auth,
|
|
106
|
+
rate_limit_per_minute=DEFAULT_RATE_LIMIT if env_rate is None else env_rate,
|
|
107
|
+
)
|
|
108
|
+
|
|
109
|
+
|
|
110
|
+
def _check_public_url(url: str) -> None:
|
|
111
|
+
parts = urlsplit(url)
|
|
112
|
+
if parts.scheme not in ("http", "https") or not parts.hostname:
|
|
113
|
+
raise ServeConfigError(f"the public URL must be an http(s) URL with a host, got {url!r}")
|
|
114
|
+
if parts.path not in ("", "/") or parts.query or parts.fragment:
|
|
115
|
+
raise ServeConfigError(
|
|
116
|
+
f"the public URL must be the server's origin only (https://host), got {url!r}"
|
|
117
|
+
)
|
|
118
|
+
if parts.scheme == "http" and not is_loopback(parts.hostname):
|
|
119
|
+
raise ServeConfigError(
|
|
120
|
+
f"the public URL must use https unless it is a loopback address, got {url!r}"
|
|
121
|
+
)
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
def validate(server: Server, options: HttpOptions, *, auth_configured: bool) -> None:
|
|
125
|
+
"""Refuse configurations that would expose a store without sign-in.
|
|
126
|
+
|
|
127
|
+
Without sign-in, HTTP mode starts only with an explicit ``--no-auth``, only on a
|
|
128
|
+
loopback address, and only without a public URL: that is a local test, nothing
|
|
129
|
+
more. A tunnel reaches a loopback server just as well as a public one, which is
|
|
130
|
+
why loopback alone is not enough to skip sign-in.
|
|
131
|
+
"""
|
|
132
|
+
if not 1 <= options.port <= 65535:
|
|
133
|
+
raise ServeConfigError(f"the port must be between 1 and 65535, got {options.port}")
|
|
134
|
+
if options.rate_limit_per_minute < 0:
|
|
135
|
+
raise ServeConfigError(f"{server.var('RATE_LIMIT_PER_MINUTE')} must be 0 (off) or more")
|
|
136
|
+
if not options.path.startswith("/"):
|
|
137
|
+
raise ServeConfigError(f"the endpoint path must start with '/', got {options.path!r}")
|
|
138
|
+
if options.public_url:
|
|
139
|
+
_check_public_url(options.public_url)
|
|
140
|
+
if auth_configured:
|
|
141
|
+
if options.no_auth:
|
|
142
|
+
raise ServeConfigError("--no-auth was given but sign-in is configured; drop one")
|
|
143
|
+
if not options.public_url:
|
|
144
|
+
raise ServeConfigError(
|
|
145
|
+
"sign-in needs the server's public URL "
|
|
146
|
+
f"(--public-url or {server.var('PUBLIC_URL')}): "
|
|
147
|
+
"GitHub and Claude are sent back to it"
|
|
148
|
+
)
|
|
149
|
+
return
|
|
150
|
+
if not options.no_auth:
|
|
151
|
+
raise ServeConfigError(
|
|
152
|
+
"HTTP mode needs GitHub sign-in configured (docs/remote-access.md). "
|
|
153
|
+
"For a local test only, add --no-auth."
|
|
154
|
+
)
|
|
155
|
+
if not is_loopback(options.host):
|
|
156
|
+
raise ServeConfigError(
|
|
157
|
+
f"--no-auth is for local testing only: bind to a loopback address, not {options.host}"
|
|
158
|
+
)
|
|
159
|
+
if options.public_url:
|
|
160
|
+
raise ServeConfigError("--no-auth can't be combined with a public URL")
|
|
161
|
+
|
|
162
|
+
|
|
163
|
+
def http_app_kwargs(options: HttpOptions) -> dict[str, Any]:
|
|
164
|
+
"""The keyword arguments shared by ``FastMCP.run`` and ``FastMCP.http_app``.
|
|
165
|
+
|
|
166
|
+
Kept in one place so the tests build exactly the app that ``serve`` runs.
|
|
167
|
+
"""
|
|
168
|
+
allowed_hosts = [options.public_host] if options.public_host else []
|
|
169
|
+
return {
|
|
170
|
+
"path": options.path,
|
|
171
|
+
"stateless_http": True,
|
|
172
|
+
"json_response": True,
|
|
173
|
+
# Strict Host/Origin checking: loopback names plus the public host only. A
|
|
174
|
+
# request naming any other Host is answered 421 before it reaches MCP.
|
|
175
|
+
"host_origin_protection": True,
|
|
176
|
+
"allowed_hosts": allowed_hosts,
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
|
|
180
|
+
def run_http(server: FastMCP, options: HttpOptions) -> None:
|
|
181
|
+
"""Serve ``server`` over streamable HTTP until interrupted."""
|
|
182
|
+
server.run(
|
|
183
|
+
transport="http",
|
|
184
|
+
host=options.host,
|
|
185
|
+
port=options.port,
|
|
186
|
+
show_banner=False,
|
|
187
|
+
# The access log would record the OAuth callback's query string, which
|
|
188
|
+
# carries the authorization code. Tool calls are logged by audit.py.
|
|
189
|
+
uvicorn_config={"access_log": False},
|
|
190
|
+
**http_app_kwargs(options),
|
|
191
|
+
)
|
|
192
|
+
|
|
193
|
+
|
|
194
|
+
def choose_transport(
|
|
195
|
+
server: Server, flag: str | None, environ: Mapping[str, str] | None = None
|
|
196
|
+
) -> str:
|
|
197
|
+
"""The transport ``serve`` uses: the flag, else ``<prefix>TRANSPORT``, else stdio.
|
|
198
|
+
|
|
199
|
+
Never FastMCP's own ``FASTMCP_TRANSPORT``: ``serve`` without an explicit HTTP
|
|
200
|
+
transport must never listen on the network, where none of HTTP mode's checks
|
|
201
|
+
(sign-in, loopback, the Host check) would have run. So a server runs stdio with
|
|
202
|
+
``server.run(transport="stdio")``, named.
|
|
203
|
+
"""
|
|
204
|
+
env = os.environ if environ is None else environ
|
|
205
|
+
name = server.var("TRANSPORT")
|
|
206
|
+
transport = flag or env.get(name) or "stdio"
|
|
207
|
+
if transport not in TRANSPORTS:
|
|
208
|
+
raise ServeConfigError(f"{name} must be one of {', '.join(TRANSPORTS)}")
|
|
209
|
+
return transport
|
|
210
|
+
|
|
211
|
+
|
|
212
|
+
def run_stdio(server: FastMCP) -> None:
|
|
213
|
+
"""Serve ``server`` over stdio: named, never left to ``FASTMCP_TRANSPORT``."""
|
|
214
|
+
server.run(transport="stdio")
|
|
215
|
+
|
|
216
|
+
|
|
217
|
+
def refuse_http_flags(flags: Mapping[str, object]) -> None:
|
|
218
|
+
"""On stdio, refuse every HTTP-only flag that was given (``{"--host": value, ...}``).
|
|
219
|
+
|
|
220
|
+
A flag counts as given when its value isn't None; pass ``True or None`` for a switch.
|
|
221
|
+
"""
|
|
222
|
+
given = [flag for flag, value in flags.items() if value is not None]
|
|
223
|
+
if given:
|
|
224
|
+
raise ServeConfigError(f"{', '.join(given)} only apply to --transport http")
|
|
225
|
+
|
|
226
|
+
|
|
227
|
+
def build_middleware(
|
|
228
|
+
server: Server,
|
|
229
|
+
*,
|
|
230
|
+
allowed_ids: frozenset[str] | None,
|
|
231
|
+
rate_limit_per_minute: int,
|
|
232
|
+
named_causes: Sequence[type[BaseException]] = (),
|
|
233
|
+
signed_in: bool,
|
|
234
|
+
clients: RegisteredClients | None = None,
|
|
235
|
+
) -> list[Middleware]:
|
|
236
|
+
"""The middleware every server puts in front of its tools, in order.
|
|
237
|
+
|
|
238
|
+
The per-caller rate limit (``rate_limit_per_minute``, 0 = off), the allow-list
|
|
239
|
+
check as a second layer behind the token verifier, then the audit line. With
|
|
240
|
+
sign-in (``signed_in``), ``allowed_ids`` is required. ``clients`` is the sign-in
|
|
241
|
+
provider (``auth.build_auth``'s proxy), whose registrations name the clients.
|
|
242
|
+
"""
|
|
243
|
+
if signed_in and not allowed_ids:
|
|
244
|
+
raise ValueError("a server with sign-in needs its allowed GitHub ids")
|
|
245
|
+
middleware: list[Middleware] = []
|
|
246
|
+
if rate_limit_per_minute:
|
|
247
|
+
middleware.append(rate_limit(rate_limit_per_minute))
|
|
248
|
+
if allowed_ids:
|
|
249
|
+
middleware.append(AuthMiddleware(auth=allowlist_check(allowed_ids)))
|
|
250
|
+
names = ClientNames(clients) if clients is not None else None
|
|
251
|
+
middleware.append(AuditMiddleware(server, named_causes, names))
|
|
252
|
+
return middleware
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
"""Search by meaning (and by words) over a server's items: the ``semantic`` extra.
|
|
2
|
+
|
|
3
|
+
A server supplies a :class:`~.types.Source` (its items, their versions, which are
|
|
4
|
+
visible) and gets an :class:`~.engine.Engine` that keeps an index of them in step
|
|
5
|
+
and searches it. Nothing here imports an optional dependency until a store or an
|
|
6
|
+
embedder is built (:mod:`.stores`, :mod:`.embedders`).
|
|
7
|
+
"""
|