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.
@@ -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
+ """