litestar-mcp-server 0.0.1__tar.gz

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,42 @@
1
+ # Python
2
+ __pycache__/
3
+ *.py[cod]
4
+ *.egg-info/
5
+ .eggs/
6
+
7
+ # Build artifacts
8
+ /dist/
9
+ /build/
10
+ /site/
11
+ /public/
12
+
13
+ # uv / venv
14
+ .venv/
15
+ uv.lock.bak
16
+
17
+ # Tool caches
18
+ .pytest_cache/
19
+ .ruff_cache/
20
+ .pyright/
21
+ .mypy_cache/
22
+ .moon/cache/
23
+
24
+ # Editor
25
+ .vscode/
26
+ .idea/
27
+ *.swp
28
+
29
+ # Local session logs
30
+ logs/
31
+
32
+ # Personal, machine-specific agent overrides (AGENTS.md is tracked)
33
+ AGENTS.local.md
34
+ CLAUDE.local.md
35
+
36
+ # Claude Code: per-machine local settings + worktrees are local; .claude/settings.json IS tracked.
37
+ .claude/settings.local.json
38
+ .claude/worktrees/
39
+
40
+ # Local agent wiring: names cabildo-issues-mcp, which is not a dependency of this
41
+ # package. docs/issues/ IS tracked — the register is plain markdown anyone can read.
42
+ .mcp.json
@@ -0,0 +1,15 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented in this file.
4
+
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
+
8
+ ## [Unreleased]
9
+
10
+ ### Added
11
+
12
+ - `McpServer` with `initialize`, `ping`, `tools/list` and `tools/call`; protocol version negotiation.
13
+ - `Tool` with `title`, `effect` (read, additive, destructive), `scope` and `visible`.
14
+ - `mcp_handlers`: the Litestar GET (405) and POST routes, with guards, dependencies and a scopes getter.
15
+ - `Arguments` typed getters, JSON Schema helpers, a result size cap.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Jorge Cardona
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,138 @@
1
+ Metadata-Version: 2.5
2
+ Name: litestar-mcp-server
3
+ Version: 0.0.1
4
+ Summary: A small MCP server for Litestar, with no SDK: tools with titles, read or destructive hints and scopes, over streamable HTTP
5
+ Project-URL: Homepage, https://gitlab.com/cardona-oss/litestar-mcp-server
6
+ Project-URL: Repository, https://gitlab.com/cardona-oss/litestar-mcp-server
7
+ Project-URL: Documentation, https://cardona-oss.gitlab.io/litestar-mcp-server/
8
+ Project-URL: Changelog, https://gitlab.com/cardona-oss/litestar-mcp-server/-/blob/main/CHANGELOG.md
9
+ Project-URL: Issues, https://gitlab.com/cardona-oss/litestar-mcp-server/-/issues
10
+ Author-email: Jorge Cardona <jorgeecardona@gmail.com>
11
+ License-Expression: MIT
12
+ License-File: LICENSE
13
+ Keywords: ai-agents,litestar,mcp,model-context-protocol,plugin,tools
14
+ Classifier: Development Status :: 4 - Beta
15
+ Classifier: Intended Audience :: Developers
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Programming Language :: Python :: 3.13
19
+ Classifier: Topic :: Software Development :: Libraries
20
+ Classifier: Typing :: Typed
21
+ Requires-Python: >=3.12
22
+ Requires-Dist: litestar>=2.23
23
+ Requires-Dist: msgspec>=0.18
24
+ Provides-Extra: docs
25
+ Requires-Dist: mkdocs-llmstxt>=0.5; extra == 'docs'
26
+ Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
27
+ Requires-Dist: mkdocs>=1.6; extra == 'docs'
28
+ Requires-Dist: mkdocstrings[python]>=0.27; extra == 'docs'
29
+ Description-Content-Type: text/markdown
30
+
31
+ <div align="center">
32
+
33
+ # litestar-mcp-server
34
+
35
+ <a href="https://pypi.org/project/litestar-mcp-server/"><img alt="pypi" src="https://img.shields.io/pypi/v/litestar-mcp-server?label=pypi&labelColor=111"></a>
36
+ <a href="https://pypi.org/project/litestar-mcp-server/"><img alt="python" src="https://img.shields.io/pypi/pyversions/litestar-mcp-server?label=python&labelColor=111"></a>
37
+ <a href="https://cardona-oss.gitlab.io/litestar-mcp-server/"><img alt="docs" src="https://img.shields.io/badge/docs-cardona--oss.gitlab.io-c9a227?labelColor=111"></a>
38
+ <a href="https://gitlab.com/cardona-oss/litestar-mcp-server/-/pipelines"><img alt="pipeline" src="https://img.shields.io/gitlab/pipeline-status/cardona-oss%2Flitestar-mcp-server?branch=main&label=pipeline&labelColor=111"></a>
39
+ <a href="https://gitlab.com/cardona-oss/litestar-mcp-server/-/blob/main/LICENSE"><img alt="license" src="https://img.shields.io/badge/license-MIT-blue?labelColor=111"></a>
40
+
41
+ <a href="https://cardona-oss.gitlab.io/litestar-mcp-server/">Documentation</a> ·
42
+ <a href="https://cardona-oss.gitlab.io/litestar-mcp-server/api/">API reference</a> ·
43
+ <a href="https://gitlab.com/cardona-oss/litestar-mcp-server/-/blob/main/CHANGELOG.md">Changelog</a> ·
44
+ <a href="https://gitlab.com/cardona-oss/litestar-mcp-server/-/issues">Issues</a> ·
45
+ <a href="https://gitlab.com/cardona-oss/litestar-mcp-server">Source</a>
46
+
47
+ </div>
48
+
49
+ ---
50
+
51
+ ## Overview
52
+
53
+ A small MCP server for Litestar, with no SDK: tools with titles, read or destructive hints and
54
+ scopes, over streamable HTTP.
55
+
56
+ ## Install
57
+
58
+ ```bash
59
+ pip install litestar-mcp-server
60
+ ```
61
+
62
+ Requires Python 3.12+.
63
+
64
+ ## Quickstart
65
+
66
+ ```python
67
+ from dataclasses import dataclass
68
+ from litestar import Litestar
69
+ from litestar.di import Provide
70
+ from litestar_mcp_server import (
71
+ Arguments, Effect, McpConfig, McpServer, Tool, mcp_handlers, object_schema, string,
72
+ )
73
+
74
+ @dataclass(frozen=True, slots=True)
75
+ class Ctx: # whatever your tools need about the caller
76
+ user: str
77
+
78
+ async def add_note(ctx: Ctx, args: Arguments) -> str:
79
+ return f"added {args.string('text')!r} for {ctx.user}"
80
+
81
+ server = McpServer(
82
+ config=McpConfig(name="notes", version="0.1.0"),
83
+ tools=[Tool(
84
+ name="add_note", title="Add a note", effect=Effect.ADDITIVE,
85
+ description="Add a note for the signed-in user.",
86
+ input_schema=object_schema({"text": string("the note")}, required=("text",)),
87
+ handler=add_note, scope="notes:write",
88
+ )],
89
+ )
90
+
91
+ async def build_ctx() -> Ctx: # a normal Litestar dependency
92
+ return Ctx(user="demo")
93
+
94
+ app = Litestar(mcp_handlers(server, dependencies={"mcp_context": Provide(build_ctx)}))
95
+ ```
96
+
97
+ Add `guards=[...]` for authentication and `scopes=lambda request: ...` so a tool's `scope` is
98
+ checked. With [litestar-oauth-server](https://pypi.org/project/litestar-oauth-server/) those are
99
+ `bearer_guard(...)` and `verified_token(request).scopes`. See `examples/basic.py`.
100
+
101
+ ## Why litestar-mcp-server
102
+
103
+ An MCP endpoint for a SaaS product is a small thing: JSON-RPC over one POST route. The official SDK
104
+ mounts a second web stack with its own auth and lifespan. This library is the small thing, as a
105
+ normal Litestar route, so auth, dependency injection and logging are the ones your app already has.
106
+ It also makes the connector-directory rules hard to forget: every tool needs a title of at most 64
107
+ characters and an effect, and the hints come from the effect.
108
+
109
+ ## Key features
110
+
111
+ - Stateless streamable HTTP (2025-11-25, 2025-06-18, 2025-03-26): one JSON object per POST, 405 on GET.
112
+ - `Effect.READ`, `ADDITIVE` or `DESTRUCTIVE` per tool, giving `readOnlyHint` or `destructiveHint`.
113
+ - `title` at the top level and in `annotations`.
114
+ - Per-tool `scope`, and per-caller `visible` (operator tools do not exist for others).
115
+ - Failures reach the agent as readable results; unexpected errors never leak details.
116
+ - A cap on result size, so a tool cannot dump a database.
117
+ - Typed argument getters, tiny JSON Schema helpers, frozen dataclasses throughout.
118
+ - No SDK and no pydantic: Litestar and msgspec only.
119
+
120
+ Not included: resources, prompts, SSE streams, sessions. Tools only.
121
+
122
+ ## Links
123
+
124
+ - **Documentation:** https://cardona-oss.gitlab.io/litestar-mcp-server/
125
+ - **Source:** https://gitlab.com/cardona-oss/litestar-mcp-server
126
+ - **Issues:** https://gitlab.com/cardona-oss/litestar-mcp-server/-/issues
127
+ - **PyPI:** https://pypi.org/project/litestar-mcp-server/
128
+ - **Changelog:** [CHANGELOG.md](https://gitlab.com/cardona-oss/litestar-mcp-server/-/blob/main/CHANGELOG.md)
129
+
130
+ ## Contributing
131
+
132
+ Developer setup, the dev loop, and the release process live in
133
+ [CONTRIBUTING.md](https://gitlab.com/cardona-oss/litestar-mcp-server/-/blob/main/CONTRIBUTING.md). In short: `uv sync && make install-hooks`, then
134
+ `make check` runs the same gate CI runs.
135
+
136
+ ## License
137
+
138
+ MIT © 2026 Jorge Cardona (see [LICENSE](https://gitlab.com/cardona-oss/litestar-mcp-server/-/blob/main/LICENSE)).
@@ -0,0 +1,108 @@
1
+ <div align="center">
2
+
3
+ # litestar-mcp-server
4
+
5
+ <a href="https://pypi.org/project/litestar-mcp-server/"><img alt="pypi" src="https://img.shields.io/pypi/v/litestar-mcp-server?label=pypi&labelColor=111"></a>
6
+ <a href="https://pypi.org/project/litestar-mcp-server/"><img alt="python" src="https://img.shields.io/pypi/pyversions/litestar-mcp-server?label=python&labelColor=111"></a>
7
+ <a href="https://cardona-oss.gitlab.io/litestar-mcp-server/"><img alt="docs" src="https://img.shields.io/badge/docs-cardona--oss.gitlab.io-c9a227?labelColor=111"></a>
8
+ <a href="https://gitlab.com/cardona-oss/litestar-mcp-server/-/pipelines"><img alt="pipeline" src="https://img.shields.io/gitlab/pipeline-status/cardona-oss%2Flitestar-mcp-server?branch=main&label=pipeline&labelColor=111"></a>
9
+ <a href="https://gitlab.com/cardona-oss/litestar-mcp-server/-/blob/main/LICENSE"><img alt="license" src="https://img.shields.io/badge/license-MIT-blue?labelColor=111"></a>
10
+
11
+ <a href="https://cardona-oss.gitlab.io/litestar-mcp-server/">Documentation</a> ·
12
+ <a href="https://cardona-oss.gitlab.io/litestar-mcp-server/api/">API reference</a> ·
13
+ <a href="https://gitlab.com/cardona-oss/litestar-mcp-server/-/blob/main/CHANGELOG.md">Changelog</a> ·
14
+ <a href="https://gitlab.com/cardona-oss/litestar-mcp-server/-/issues">Issues</a> ·
15
+ <a href="https://gitlab.com/cardona-oss/litestar-mcp-server">Source</a>
16
+
17
+ </div>
18
+
19
+ ---
20
+
21
+ ## Overview
22
+
23
+ A small MCP server for Litestar, with no SDK: tools with titles, read or destructive hints and
24
+ scopes, over streamable HTTP.
25
+
26
+ ## Install
27
+
28
+ ```bash
29
+ pip install litestar-mcp-server
30
+ ```
31
+
32
+ Requires Python 3.12+.
33
+
34
+ ## Quickstart
35
+
36
+ ```python
37
+ from dataclasses import dataclass
38
+ from litestar import Litestar
39
+ from litestar.di import Provide
40
+ from litestar_mcp_server import (
41
+ Arguments, Effect, McpConfig, McpServer, Tool, mcp_handlers, object_schema, string,
42
+ )
43
+
44
+ @dataclass(frozen=True, slots=True)
45
+ class Ctx: # whatever your tools need about the caller
46
+ user: str
47
+
48
+ async def add_note(ctx: Ctx, args: Arguments) -> str:
49
+ return f"added {args.string('text')!r} for {ctx.user}"
50
+
51
+ server = McpServer(
52
+ config=McpConfig(name="notes", version="0.1.0"),
53
+ tools=[Tool(
54
+ name="add_note", title="Add a note", effect=Effect.ADDITIVE,
55
+ description="Add a note for the signed-in user.",
56
+ input_schema=object_schema({"text": string("the note")}, required=("text",)),
57
+ handler=add_note, scope="notes:write",
58
+ )],
59
+ )
60
+
61
+ async def build_ctx() -> Ctx: # a normal Litestar dependency
62
+ return Ctx(user="demo")
63
+
64
+ app = Litestar(mcp_handlers(server, dependencies={"mcp_context": Provide(build_ctx)}))
65
+ ```
66
+
67
+ Add `guards=[...]` for authentication and `scopes=lambda request: ...` so a tool's `scope` is
68
+ checked. With [litestar-oauth-server](https://pypi.org/project/litestar-oauth-server/) those are
69
+ `bearer_guard(...)` and `verified_token(request).scopes`. See `examples/basic.py`.
70
+
71
+ ## Why litestar-mcp-server
72
+
73
+ An MCP endpoint for a SaaS product is a small thing: JSON-RPC over one POST route. The official SDK
74
+ mounts a second web stack with its own auth and lifespan. This library is the small thing, as a
75
+ normal Litestar route, so auth, dependency injection and logging are the ones your app already has.
76
+ It also makes the connector-directory rules hard to forget: every tool needs a title of at most 64
77
+ characters and an effect, and the hints come from the effect.
78
+
79
+ ## Key features
80
+
81
+ - Stateless streamable HTTP (2025-11-25, 2025-06-18, 2025-03-26): one JSON object per POST, 405 on GET.
82
+ - `Effect.READ`, `ADDITIVE` or `DESTRUCTIVE` per tool, giving `readOnlyHint` or `destructiveHint`.
83
+ - `title` at the top level and in `annotations`.
84
+ - Per-tool `scope`, and per-caller `visible` (operator tools do not exist for others).
85
+ - Failures reach the agent as readable results; unexpected errors never leak details.
86
+ - A cap on result size, so a tool cannot dump a database.
87
+ - Typed argument getters, tiny JSON Schema helpers, frozen dataclasses throughout.
88
+ - No SDK and no pydantic: Litestar and msgspec only.
89
+
90
+ Not included: resources, prompts, SSE streams, sessions. Tools only.
91
+
92
+ ## Links
93
+
94
+ - **Documentation:** https://cardona-oss.gitlab.io/litestar-mcp-server/
95
+ - **Source:** https://gitlab.com/cardona-oss/litestar-mcp-server
96
+ - **Issues:** https://gitlab.com/cardona-oss/litestar-mcp-server/-/issues
97
+ - **PyPI:** https://pypi.org/project/litestar-mcp-server/
98
+ - **Changelog:** [CHANGELOG.md](https://gitlab.com/cardona-oss/litestar-mcp-server/-/blob/main/CHANGELOG.md)
99
+
100
+ ## Contributing
101
+
102
+ Developer setup, the dev loop, and the release process live in
103
+ [CONTRIBUTING.md](https://gitlab.com/cardona-oss/litestar-mcp-server/-/blob/main/CONTRIBUTING.md). In short: `uv sync && make install-hooks`, then
104
+ `make check` runs the same gate CI runs.
105
+
106
+ ## License
107
+
108
+ MIT © 2026 Jorge Cardona (see [LICENSE](https://gitlab.com/cardona-oss/litestar-mcp-server/-/blob/main/LICENSE)).
@@ -0,0 +1,72 @@
1
+ """A Litestar API with one MCP endpoint and two tools.
2
+
3
+ Run it with: uv run litestar --app examples.basic:app run
4
+
5
+ Authentication is a placeholder guard here. In a real app use ``bearer_guard`` from
6
+ ``litestar-oauth-server`` and read the token's scopes with ``verified_token``.
7
+ """
8
+
9
+ from dataclasses import dataclass
10
+ from typing import Any
11
+
12
+ from litestar import Litestar, Request
13
+ from litestar.di import Provide
14
+
15
+ from litestar_mcp_server import (
16
+ Arguments,
17
+ Effect,
18
+ McpConfig,
19
+ McpServer,
20
+ Tool,
21
+ mcp_handlers,
22
+ object_schema,
23
+ string,
24
+ )
25
+
26
+
27
+ @dataclass(frozen=True, slots=True)
28
+ class Ctx:
29
+ """What the tools need about the caller. Build it from your own session or token."""
30
+
31
+ user: str
32
+
33
+
34
+ async def list_notes(ctx: Ctx, args: Arguments) -> list[str]:
35
+ return [f"note of {ctx.user}"]
36
+
37
+
38
+ async def add_note(ctx: Ctx, args: Arguments) -> str:
39
+ return f"added {args.string('text')!r} for {ctx.user}"
40
+
41
+
42
+ server = McpServer(
43
+ config=McpConfig(name="notes", version="0.1.0", instructions="Read and add the user's notes."),
44
+ tools=[
45
+ Tool(
46
+ name="list_notes",
47
+ title="List my notes",
48
+ effect=Effect.READ,
49
+ description="List the notes of the signed-in user.",
50
+ input_schema=object_schema(),
51
+ handler=list_notes,
52
+ ),
53
+ Tool(
54
+ name="add_note",
55
+ title="Add a note",
56
+ effect=Effect.ADDITIVE,
57
+ description="Add a note for the signed-in user.",
58
+ input_schema=object_schema({"text": string("the note")}, required=("text",)),
59
+ handler=add_note,
60
+ scope="notes:write",
61
+ ),
62
+ ],
63
+ )
64
+
65
+
66
+ async def build_ctx(request: Request[Any, Any, Any]) -> Ctx:
67
+ return Ctx(user="demo")
68
+
69
+
70
+ app = Litestar(
71
+ mcp_handlers(server, path="/mcp", dependencies={"mcp_context": Provide(build_ctx)}),
72
+ )
@@ -0,0 +1,116 @@
1
+ [project]
2
+ name = "litestar-mcp-server"
3
+ dynamic = ["version"] # the single source of truth is __version__ in src/litestar_mcp_server/__init__.py (see [tool.hatch.version])
4
+ description = "A small MCP server for Litestar, with no SDK: tools with titles, read or destructive hints and scopes, over streamable HTTP"
5
+ readme = "README.md"
6
+ requires-python = ">=3.12"
7
+ license = "MIT"
8
+ license-files = ["LICENSE"]
9
+ authors = [{ name = "Jorge Cardona", email = "jorgeecardona@gmail.com" }]
10
+ keywords = ["litestar", "mcp", "model-context-protocol", "ai-agents", "tools", "plugin"]
11
+ classifiers = [
12
+ "Development Status :: 4 - Beta",
13
+ "Intended Audience :: Developers",
14
+ "Programming Language :: Python :: 3",
15
+ "Programming Language :: Python :: 3.12",
16
+ "Programming Language :: Python :: 3.13",
17
+ "Topic :: Software Development :: Libraries",
18
+ "Typing :: Typed",
19
+ ]
20
+ dependencies = [
21
+ "litestar>=2.23",
22
+ "msgspec>=0.18",
23
+ ]
24
+
25
+ [project.optional-dependencies]
26
+ # docs are an *extra* (not a uv dependency-group) so Read the Docs can install them via pip
27
+ docs = [
28
+ "mkdocs>=1.6",
29
+ "mkdocs-material>=9.5",
30
+ "mkdocstrings[python]>=0.27",
31
+ "mkdocs-llmstxt>=0.5",
32
+ ]
33
+
34
+ [project.urls]
35
+ Homepage = "https://gitlab.com/cardona-oss/litestar-mcp-server"
36
+ Repository = "https://gitlab.com/cardona-oss/litestar-mcp-server"
37
+ Documentation = "https://cardona-oss.gitlab.io/litestar-mcp-server/"
38
+ Changelog = "https://gitlab.com/cardona-oss/litestar-mcp-server/-/blob/main/CHANGELOG.md"
39
+ Issues = "https://gitlab.com/cardona-oss/litestar-mcp-server/-/issues"
40
+
41
+ [build-system]
42
+ requires = ["hatchling"]
43
+ build-backend = "hatchling.build"
44
+
45
+ [tool.hatch.version]
46
+ # The version lives as __version__ in the package itself; hatchling reads it (by regex, no import) so
47
+ # pyproject and the runtime never disagree. scripts/bump-version rewrites that literal.
48
+ path = "src/litestar_mcp_server/__init__.py"
49
+
50
+ [tool.hatch.build.targets.wheel]
51
+ packages = ["src/litestar_mcp_server"]
52
+
53
+ [tool.hatch.build.targets.sdist]
54
+ include = ["src", "tests", "examples", "README.md", "CHANGELOG.md", "LICENSE"]
55
+
56
+ [tool.uv]
57
+ # The version is dynamic (hatchling reads __version__ from the file below), so uv must watch it too:
58
+ # declaring cache-keys REPLACES uv's defaults, so pyproject.toml is listed explicitly alongside it.
59
+ # Without __init__.py here, bumping the version would not trigger an editable reinstall.
60
+ cache-keys = [{ file = "pyproject.toml" }, { file = "src/litestar_mcp_server/__init__.py" }]
61
+
62
+ [dependency-groups]
63
+ dev = ["ruff>=0.6", "pyright[nodejs]>=1.1.390", "pytest>=8", "httpx>=0.27"]
64
+
65
+ [tool.pytest.ini_options]
66
+ testpaths = ["tests"]
67
+ addopts = "-q"
68
+ pythonpath = ["."]
69
+
70
+ [tool.ruff]
71
+ line-length = 100
72
+ target-version = "py312"
73
+ src = ["src", "tests"]
74
+
75
+ [tool.ruff.lint]
76
+ select = ["ALL"]
77
+ # The canonical base ignore list shared across the oss/ libraries. E501 (line length) is handled by
78
+ # the formatter; COM812/ISC001 conflict with the formatter; D1/D401 relax docstring presence/mood;
79
+ # TRY003/EM101/EM102 allow inline exception messages; CPY001 drops the copyright-header demand;
80
+ # PLC0415 allows non-top-level imports; TC001/TC002/TC003 don't force type-only import blocks.
81
+ ignore = [
82
+ "E501",
83
+ "COM812",
84
+ "ISC001",
85
+ "D1",
86
+ "D401",
87
+ "TRY003",
88
+ "EM101",
89
+ "EM102",
90
+ "CPY001",
91
+ "PLC0415",
92
+ "TC001",
93
+ "TC002",
94
+ "TC003",
95
+ ]
96
+
97
+ [tool.ruff.lint.pydocstyle]
98
+ convention = "pep257"
99
+
100
+ [tool.ruff.lint.per-file-ignores]
101
+ # Tests may assert (S101), use magic values (PLR2004), take unused fixtures (ARG), pass Any to typed
102
+ # calls (ANN401), and group assertions pytest would otherwise split (PT018).
103
+ "tests/**/*.py" = ["S101", "S105", "S106", "PLR0913", "PLR2004", "ARG", "ANN401", "PT018"]
104
+ # Examples are scripts, not a package.
105
+ "examples/**/*.py" = ["INP001", "ARG001"]
106
+
107
+ [tool.ruff.lint.isort]
108
+ known-first-party = ["litestar_mcp_server"]
109
+
110
+ [tool.pyright]
111
+ include = ["src", "tests", "examples"]
112
+ extraPaths = ["src"]
113
+ pythonVersion = "3.12"
114
+ typeCheckingMode = "strict"
115
+ venvPath = "."
116
+ venv = ".venv"
@@ -0,0 +1,41 @@
1
+ """A small MCP server for Litestar, with no SDK."""
2
+
3
+ from litestar_mcp_server.plugin import mcp_handlers
4
+ from litestar_mcp_server.protocol import LATEST_PROTOCOL_VERSION, SUPPORTED_PROTOCOL_VERSIONS
5
+ from litestar_mcp_server.server import McpConfig, McpResponse, McpServer
6
+ from litestar_mcp_server.tools import (
7
+ TITLE_MAX,
8
+ Arguments,
9
+ Effect,
10
+ JsonObject,
11
+ JsonValue,
12
+ Tool,
13
+ ToolError,
14
+ boolean,
15
+ integer,
16
+ object_schema,
17
+ string,
18
+ )
19
+
20
+ __version__ = "0.0.1" # the single source of truth; pyproject reads it via [tool.hatch.version]
21
+
22
+ __all__ = [
23
+ "LATEST_PROTOCOL_VERSION",
24
+ "SUPPORTED_PROTOCOL_VERSIONS",
25
+ "TITLE_MAX",
26
+ "Arguments",
27
+ "Effect",
28
+ "JsonObject",
29
+ "JsonValue",
30
+ "McpConfig",
31
+ "McpResponse",
32
+ "McpServer",
33
+ "Tool",
34
+ "ToolError",
35
+ "__version__",
36
+ "boolean",
37
+ "integer",
38
+ "mcp_handlers",
39
+ "object_schema",
40
+ "string",
41
+ ]
@@ -0,0 +1,75 @@
1
+ """The Litestar shell: one route at ``path`` that feeds ``McpServer.handle``.
2
+
3
+ mcp = mcp_handlers(
4
+ server,
5
+ path="/mcp",
6
+ guards=[bearer_guard(...)], # authentication (401 before anything else)
7
+ dependencies={"mcp_context": Provide(build_ctx)}, # your Ctx, built with Litestar's own DI
8
+ scopes=lambda request: verified_token(request).scopes, # optional
9
+ )
10
+ app = Litestar([*mcp, ...])
11
+
12
+ The context is a normal Litestar dependency named ``mcp_context``, so repositories, sessions and
13
+ the current user come from the same injection every other route uses.
14
+ """
15
+
16
+ from __future__ import annotations
17
+
18
+ from collections.abc import Awaitable, Callable, Mapping, Sequence
19
+ from typing import TYPE_CHECKING, Any
20
+
21
+ from litestar import Request, Response, get, post
22
+ from litestar.di import NamedDependency
23
+ from litestar.handlers import HTTPRouteHandler
24
+
25
+ from litestar_mcp_server.server import McpServer
26
+
27
+ if TYPE_CHECKING:
28
+ from litestar.connection import ASGIConnection
29
+ from litestar.di import Provide
30
+ from litestar.handlers.base import BaseRouteHandler
31
+
32
+ type McpGuard = Callable[
33
+ [ASGIConnection[Any, Any, Any, Any], BaseRouteHandler], Awaitable[None] | None
34
+ ]
35
+ """A Litestar guard function; pass it in ``guards=[...]``."""
36
+
37
+ ScopesGetter = Callable[[Request[Any, Any, Any]], frozenset[str] | None]
38
+
39
+
40
+ def mcp_handlers[Ctx](
41
+ server: McpServer[Ctx],
42
+ *,
43
+ path: str = "/mcp",
44
+ guards: Sequence[McpGuard] = (),
45
+ dependencies: Mapping[str, Provide] | None = None,
46
+ scopes: ScopesGetter | None = None,
47
+ ) -> list[HTTPRouteHandler]:
48
+ """The GET (405) and POST handlers for ``server`` at ``path``."""
49
+
50
+ @get(path, guards=list(guards), include_in_schema=False)
51
+ async def no_stream() -> Response[None]:
52
+ # A server offering no server-initiated SSE stream MUST answer GET with 405.
53
+ return Response(None, status_code=405)
54
+
55
+ @post(
56
+ path,
57
+ guards=list(guards),
58
+ dependencies=dict(dependencies or {}),
59
+ status_code=200,
60
+ include_in_schema=False,
61
+ )
62
+ async def rpc(
63
+ request: Request[Any, Any, Any],
64
+ mcp_context: NamedDependency[Any],
65
+ ) -> Response[bytes]:
66
+ headers = {k.lower(): v for k, v in request.headers.items()}
67
+ answer = await server.handle(
68
+ body=await request.body(),
69
+ headers=headers,
70
+ ctx=mcp_context,
71
+ scopes=scopes(request) if scopes is not None else None,
72
+ )
73
+ return Response(answer.body, status_code=answer.status, media_type=answer.media_type)
74
+
75
+ return [no_stream, rpc]