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.
- litestar_mcp_server-0.0.1/.gitignore +42 -0
- litestar_mcp_server-0.0.1/CHANGELOG.md +15 -0
- litestar_mcp_server-0.0.1/LICENSE +21 -0
- litestar_mcp_server-0.0.1/PKG-INFO +138 -0
- litestar_mcp_server-0.0.1/README.md +108 -0
- litestar_mcp_server-0.0.1/examples/basic.py +72 -0
- litestar_mcp_server-0.0.1/pyproject.toml +116 -0
- litestar_mcp_server-0.0.1/src/litestar_mcp_server/__init__.py +41 -0
- litestar_mcp_server-0.0.1/src/litestar_mcp_server/plugin.py +75 -0
- litestar_mcp_server-0.0.1/src/litestar_mcp_server/protocol.py +158 -0
- litestar_mcp_server-0.0.1/src/litestar_mcp_server/py.typed +0 -0
- litestar_mcp_server-0.0.1/src/litestar_mcp_server/server.py +212 -0
- litestar_mcp_server-0.0.1/src/litestar_mcp_server/tools.py +197 -0
- litestar_mcp_server-0.0.1/tests/__init__.py +0 -0
- litestar_mcp_server-0.0.1/tests/conftest.py +119 -0
- litestar_mcp_server-0.0.1/tests/test_http.py +89 -0
- litestar_mcp_server-0.0.1/tests/test_server.py +217 -0
|
@@ -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]
|