python-docs-mcp-server 0.1.2__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.
- mcp_server_python_docs/__init__.py +17 -0
- mcp_server_python_docs/__main__.py +574 -0
- mcp_server_python_docs/app_context.py +33 -0
- mcp_server_python_docs/data/synonyms.yaml +194 -0
- mcp_server_python_docs/detection.py +82 -0
- mcp_server_python_docs/diagnostics.py +74 -0
- mcp_server_python_docs/errors.py +33 -0
- mcp_server_python_docs/ingestion/__init__.py +1 -0
- mcp_server_python_docs/ingestion/cpython_versions.py +32 -0
- mcp_server_python_docs/ingestion/inventory.py +178 -0
- mcp_server_python_docs/ingestion/publish.py +504 -0
- mcp_server_python_docs/ingestion/sphinx_json.py +617 -0
- mcp_server_python_docs/models.py +216 -0
- mcp_server_python_docs/py.typed +0 -0
- mcp_server_python_docs/retrieval/__init__.py +31 -0
- mcp_server_python_docs/retrieval/budget.py +63 -0
- mcp_server_python_docs/retrieval/query.py +183 -0
- mcp_server_python_docs/retrieval/ranker.py +369 -0
- mcp_server_python_docs/server.py +329 -0
- mcp_server_python_docs/services/__init__.py +7 -0
- mcp_server_python_docs/services/cache.py +111 -0
- mcp_server_python_docs/services/content.py +155 -0
- mcp_server_python_docs/services/observability.py +130 -0
- mcp_server_python_docs/services/package_docs.py +161 -0
- mcp_server_python_docs/services/persistent_cache.py +147 -0
- mcp_server_python_docs/services/search.py +111 -0
- mcp_server_python_docs/services/version.py +47 -0
- mcp_server_python_docs/services/version_resolution.py +79 -0
- mcp_server_python_docs/storage/__init__.py +1 -0
- mcp_server_python_docs/storage/db.py +146 -0
- mcp_server_python_docs/storage/schema.sql +136 -0
- python_docs_mcp_server-0.1.2.dist-info/METADATA +528 -0
- python_docs_mcp_server-0.1.2.dist-info/RECORD +36 -0
- python_docs_mcp_server-0.1.2.dist-info/WHEEL +4 -0
- python_docs_mcp_server-0.1.2.dist-info/entry_points.txt +3 -0
- python_docs_mcp_server-0.1.2.dist-info/licenses/LICENSE +21 -0
|
@@ -0,0 +1,528 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: python-docs-mcp-server
|
|
3
|
+
Version: 0.1.2
|
|
4
|
+
Summary: A read-only, version-aware MCP retrieval server over Python standard library documentation
|
|
5
|
+
Author-email: Aymen Hammouda <hammouda.aymen@gmail.com>
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
License-File: LICENSE
|
|
8
|
+
Keywords: claude,documentation,llm,mcp,python
|
|
9
|
+
Classifier: Development Status :: 3 - Alpha
|
|
10
|
+
Classifier: Intended Audience :: Developers
|
|
11
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
12
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
14
|
+
Classifier: Topic :: Documentation
|
|
15
|
+
Classifier: Topic :: Software Development :: Libraries
|
|
16
|
+
Requires-Python: >=3.12
|
|
17
|
+
Requires-Dist: beautifulsoup4<5.0,>=4.12
|
|
18
|
+
Requires-Dist: click<9.0,>=8.1.7
|
|
19
|
+
Requires-Dist: markdownify<2.0,>=0.14
|
|
20
|
+
Requires-Dist: mcp<2.0.0,>=1.27.0
|
|
21
|
+
Requires-Dist: platformdirs>=4.0
|
|
22
|
+
Requires-Dist: pydantic<3.0,>=2.0.0
|
|
23
|
+
Requires-Dist: pyyaml<7.0,>=6.0
|
|
24
|
+
Requires-Dist: sphobjinv<3.0,>=2.4
|
|
25
|
+
Provides-Extra: pysqlite3
|
|
26
|
+
Requires-Dist: pysqlite3-binary>=0.5.4; extra == 'pysqlite3'
|
|
27
|
+
Description-Content-Type: text/markdown
|
|
28
|
+
|
|
29
|
+
# python-docs-mcp-server
|
|
30
|
+
|
|
31
|
+
<!-- mcp-name: io.github.ayhammouda/python-docs-mcp-server -->
|
|
32
|
+
|
|
33
|
+
[](https://github.com/ayhammouda/python-docs-mcp-server/actions/workflows/ci.yml)
|
|
34
|
+
[](LICENSE)
|
|
35
|
+
[](https://www.python.org/)
|
|
36
|
+
[](#why-teams-like-this)
|
|
37
|
+
[](https://docs.python.org/3/)
|
|
38
|
+
|
|
39
|
+
A read-only, version-aware MCP server for Python standard library
|
|
40
|
+
documentation, optimized for low-token, section-level retrieval.
|
|
41
|
+
|
|
42
|
+
It gives Claude, Cursor, Codex, and other MCP clients precise stdlib answers
|
|
43
|
+
without dumping whole documentation pages into the context window, without API
|
|
44
|
+
keys, and without depending on a hosted docs provider at query time.
|
|
45
|
+
|
|
46
|
+
## Why this exists
|
|
47
|
+
|
|
48
|
+
General-purpose docs retrieval is often noisy for Python stdlib questions:
|
|
49
|
+
|
|
50
|
+
- symbol lookups like `asyncio.TaskGroup` need exact resolution
|
|
51
|
+
- answers should be version-aware (`3.12` vs `3.13`)
|
|
52
|
+
- full-page fetches waste tokens when one section is enough
|
|
53
|
+
- official Python docs are the source of truth, but they are not packaged for
|
|
54
|
+
MCP out of the box
|
|
55
|
+
|
|
56
|
+
This server builds a local index from the official Python documentation and
|
|
57
|
+
exposes a small MCP tool surface tuned for high-signal retrieval.
|
|
58
|
+
|
|
59
|
+
## Why teams like this
|
|
60
|
+
|
|
61
|
+
- no API keys to provision, rotate, or justify
|
|
62
|
+
- official Python docs are the source of truth
|
|
63
|
+
- local index, so runtime retrieval does not depend on a third-party hosted API
|
|
64
|
+
- read-only behavior with a simple security story
|
|
65
|
+
- easy to explain in environments where external dependencies raise friction
|
|
66
|
+
|
|
67
|
+
## What you get
|
|
68
|
+
|
|
69
|
+
- exact symbol lookup from Python `objects.inv`
|
|
70
|
+
- section-level retrieval with truncation and pagination
|
|
71
|
+
- local SQLite + FTS5 index with no runtime web scraping
|
|
72
|
+
- version-aware results across indexed Python versions
|
|
73
|
+
- a deliberately small, read-only MCP tool surface
|
|
74
|
+
|
|
75
|
+
## Quick example
|
|
76
|
+
|
|
77
|
+
**Prompt**
|
|
78
|
+
|
|
79
|
+
> What does `asyncio.TaskGroup` do in Python 3.13?
|
|
80
|
+
|
|
81
|
+
**Typical flow**
|
|
82
|
+
|
|
83
|
+
1. `search_docs("asyncio.TaskGroup", kind="symbol", version="3.13")`
|
|
84
|
+
2. Call `get_docs(...)` using the slug and anchor returned by the best hit
|
|
85
|
+
|
|
86
|
+
**Result**
|
|
87
|
+
|
|
88
|
+
The model gets the exact symbol match and the relevant documentation section
|
|
89
|
+
instead of a full-page dump.
|
|
90
|
+
|
|
91
|
+
## 30-second demo
|
|
92
|
+
|
|
93
|
+
Ask your MCP client:
|
|
94
|
+
|
|
95
|
+
> In Python 3.13, how should I use `asyncio.TaskGroup` and what changed from older asyncio patterns?
|
|
96
|
+
|
|
97
|
+
The agent should use `search_docs` for the exact symbol, then `get_docs` for the
|
|
98
|
+
matching section. Instead of generic web results or an entire docs page, it gets
|
|
99
|
+
the official stdlib text for the requested Python version, trimmed to the useful
|
|
100
|
+
section.
|
|
101
|
+
|
|
102
|
+
<!-- PRE-PYPI: replace this temporary GitHub-source smoke test after the first PyPI publish -->
|
|
103
|
+
Local source smoke test until the PyPI package is published:
|
|
104
|
+
|
|
105
|
+
```bash
|
|
106
|
+
uvx --from git+https://github.com/ayhammouda/python-docs-mcp-server.git python-docs-mcp-server --version
|
|
107
|
+
```
|
|
108
|
+
<!-- /PRE-PYPI -->
|
|
109
|
+
|
|
110
|
+
## Install
|
|
111
|
+
|
|
112
|
+
<!-- PRE-PYPI: remove this entire "Before PyPI publishing" block (heading + prose + code) after the first PyPI publish -->
|
|
113
|
+
### Before PyPI publishing (install from GitHub source)
|
|
114
|
+
|
|
115
|
+
Until the first PyPI release is published, run from GitHub:
|
|
116
|
+
|
|
117
|
+
```bash
|
|
118
|
+
uvx --from git+https://github.com/ayhammouda/python-docs-mcp-server.git python-docs-mcp-server --version
|
|
119
|
+
```
|
|
120
|
+
<!-- /PRE-PYPI -->
|
|
121
|
+
|
|
122
|
+
<!-- PRE-PYPI: after the first PyPI publish, drop this "After PyPI publishing" heading so the section reads simply as "## Install" -->
|
|
123
|
+
### After PyPI publishing
|
|
124
|
+
<!-- /PRE-PYPI -->
|
|
125
|
+
|
|
126
|
+
Run directly with `uvx`:
|
|
127
|
+
|
|
128
|
+
```bash
|
|
129
|
+
uvx python-docs-mcp-server --version
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
Or install it persistently:
|
|
133
|
+
|
|
134
|
+
```bash
|
|
135
|
+
pipx install python-docs-mcp-server
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
---
|
|
139
|
+
|
|
140
|
+
If `uv` is installed but the `uv` command is not on your `PATH`, reopen your
|
|
141
|
+
shell or use `python -m uv ...` as a fallback for local contributor commands.
|
|
142
|
+
|
|
143
|
+
## First run
|
|
144
|
+
|
|
145
|
+
Build the local documentation index:
|
|
146
|
+
|
|
147
|
+
<!-- PRE-PYPI: remove the GitHub-source build-index command and the "After PyPI publishing" lead-in after the first PyPI publish; the post-PyPI code fence below survives -->
|
|
148
|
+
```bash
|
|
149
|
+
uvx --from git+https://github.com/ayhammouda/python-docs-mcp-server.git python-docs-mcp-server build-index --versions 3.10,3.11,3.12,3.13,3.14
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
After PyPI publishing, `uvx python-docs-mcp-server build-index ...` is enough.
|
|
153
|
+
<!-- /PRE-PYPI -->
|
|
154
|
+
|
|
155
|
+
<!-- PRE-PYPI: after the first PyPI publish, drop this "After PyPI publishing" heading so the section reads simply as "## First run" -->
|
|
156
|
+
### After PyPI publishing
|
|
157
|
+
<!-- /PRE-PYPI -->
|
|
158
|
+
|
|
159
|
+
```bash
|
|
160
|
+
uvx python-docs-mcp-server build-index --versions 3.10,3.11,3.12,3.13,3.14
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
If you installed the package persistently, you can drop the `uvx` prefix:
|
|
164
|
+
|
|
165
|
+
```bash
|
|
166
|
+
python-docs-mcp-server build-index --versions 3.10,3.11,3.12,3.13,3.14
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
This downloads Python's `objects.inv` files, clones CPython docs sources, runs
|
|
170
|
+
`sphinx-build -b json`, and writes an SQLite index to your local cache. Expect
|
|
171
|
+
the first build to take several minutes.
|
|
172
|
+
|
|
173
|
+
## Configure your MCP client
|
|
174
|
+
|
|
175
|
+
### Claude Desktop
|
|
176
|
+
|
|
177
|
+
Add this to your Claude Desktop configuration file:
|
|
178
|
+
|
|
179
|
+
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
|
|
180
|
+
|
|
181
|
+
**Linux:** `~/.config/Claude/claude_desktop_config.json`
|
|
182
|
+
|
|
183
|
+
**Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`
|
|
184
|
+
|
|
185
|
+
<!-- PRE-PYPI: remove the GitHub-source config and the "After PyPI publishing, use:" lead-in after the first PyPI publish; the post-PyPI config fence below survives -->
|
|
186
|
+
```json
|
|
187
|
+
{
|
|
188
|
+
"mcpServers": {
|
|
189
|
+
"python-docs": {
|
|
190
|
+
"command": "uvx",
|
|
191
|
+
"args": [
|
|
192
|
+
"--from",
|
|
193
|
+
"git+https://github.com/ayhammouda/python-docs-mcp-server.git",
|
|
194
|
+
"python-docs-mcp-server"
|
|
195
|
+
]
|
|
196
|
+
}
|
|
197
|
+
}
|
|
198
|
+
}
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
After PyPI publishing, use:
|
|
202
|
+
<!-- /PRE-PYPI -->
|
|
203
|
+
|
|
204
|
+
```json
|
|
205
|
+
{
|
|
206
|
+
"mcpServers": {
|
|
207
|
+
"python-docs": {
|
|
208
|
+
"command": "uvx",
|
|
209
|
+
"args": ["python-docs-mcp-server"]
|
|
210
|
+
}
|
|
211
|
+
}
|
|
212
|
+
}
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
Restart Claude Desktop after editing the config file.
|
|
216
|
+
|
|
217
|
+
### Cursor
|
|
218
|
+
|
|
219
|
+
Add this to your Cursor MCP settings (`.cursor/mcp.json` in your project or
|
|
220
|
+
global settings):
|
|
221
|
+
|
|
222
|
+
<!-- PRE-PYPI: remove the GitHub-source config and the "After PyPI publishing, use:" lead-in after the first PyPI publish; the post-PyPI config fence below survives -->
|
|
223
|
+
```json
|
|
224
|
+
{
|
|
225
|
+
"mcpServers": {
|
|
226
|
+
"python-docs": {
|
|
227
|
+
"command": "uvx",
|
|
228
|
+
"args": [
|
|
229
|
+
"--from",
|
|
230
|
+
"git+https://github.com/ayhammouda/python-docs-mcp-server.git",
|
|
231
|
+
"python-docs-mcp-server"
|
|
232
|
+
]
|
|
233
|
+
}
|
|
234
|
+
}
|
|
235
|
+
}
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
After PyPI publishing, use:
|
|
239
|
+
<!-- /PRE-PYPI -->
|
|
240
|
+
|
|
241
|
+
```json
|
|
242
|
+
{
|
|
243
|
+
"mcpServers": {
|
|
244
|
+
"python-docs": {
|
|
245
|
+
"command": "uvx",
|
|
246
|
+
"args": ["python-docs-mcp-server"]
|
|
247
|
+
}
|
|
248
|
+
}
|
|
249
|
+
}
|
|
250
|
+
```
|
|
251
|
+
|
|
252
|
+
### Codex
|
|
253
|
+
|
|
254
|
+
Add this to `.codex/config.toml`:
|
|
255
|
+
|
|
256
|
+
<!-- PRE-PYPI: remove the GitHub-source config and the "After PyPI publishing, use:" lead-in after the first PyPI publish; the post-PyPI config fence below survives -->
|
|
257
|
+
```toml
|
|
258
|
+
[mcp_servers.python-docs]
|
|
259
|
+
command = "uvx"
|
|
260
|
+
args = ["--from", "git+https://github.com/ayhammouda/python-docs-mcp-server.git", "python-docs-mcp-server"]
|
|
261
|
+
```
|
|
262
|
+
|
|
263
|
+
After PyPI publishing, use:
|
|
264
|
+
<!-- /PRE-PYPI -->
|
|
265
|
+
|
|
266
|
+
```toml
|
|
267
|
+
[mcp_servers.python-docs]
|
|
268
|
+
command = "uvx"
|
|
269
|
+
args = ["python-docs-mcp-server"]
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+
## How quality is verified
|
|
273
|
+
|
|
274
|
+
The repo makes quality visible with reproducible checks instead of relying on
|
|
275
|
+
marketing claims.
|
|
276
|
+
|
|
277
|
+
- CI runs `ruff`, `pyright`, and `pytest` on macOS and Linux for Python 3.12
|
|
278
|
+
and 3.13
|
|
279
|
+
- subprocess-based stdio hygiene and smoke tests protect the MCP protocol pipe
|
|
280
|
+
- packaging tests verify the wheel contents and CLI entry points
|
|
281
|
+
- curated retrieval regression tests cover exact symbol hits, version behavior,
|
|
282
|
+
missing symbols, truncation, and local-version defaults
|
|
283
|
+
- manual MCP QA is documented in
|
|
284
|
+
[`.github/INTEGRATION-TEST.md`](.github/INTEGRATION-TEST.md), with MCP
|
|
285
|
+
Inspector as the fast-feedback loop and Claude/Cursor as real-client checks
|
|
286
|
+
|
|
287
|
+
Contributor commands and validation steps live in
|
|
288
|
+
[`CONTRIBUTING.md`](CONTRIBUTING.md).
|
|
289
|
+
|
|
290
|
+
## Tools
|
|
291
|
+
|
|
292
|
+
The server currently exposes five MCP tools:
|
|
293
|
+
|
|
294
|
+
| Tool | Description |
|
|
295
|
+
|------|-------------|
|
|
296
|
+
| `search_docs` | Search Python stdlib docs by query. Supports symbol lookup (`asyncio.TaskGroup`), module search (`json`), and free-text search. Returns ranked hits with BM25 scoring and snippet excerpts. |
|
|
297
|
+
| `get_docs` | Retrieve a specific documentation page or section by slug and optional anchor. Returns markdown content with budget-enforced truncation and pagination. Retrieved results are cached on disk by Python docs version and request identity. |
|
|
298
|
+
| `lookup_package_docs` | Look up official PyPI package metadata and return package-declared documentation/homepage/source URLs. This is a controlled PyPI metadata lookup, not generic web search. |
|
|
299
|
+
| `list_versions` | List all indexed Python versions with metadata. |
|
|
300
|
+
| `detect_python_version` | Detect the user's local Python version and report whether it matches an indexed documentation version. |
|
|
301
|
+
|
|
302
|
+
## Why not Context7 or generic docs retrieval?
|
|
303
|
+
|
|
304
|
+
Use this server when you want precise local Python docs retrieval rather than
|
|
305
|
+
broad web search:
|
|
306
|
+
|
|
307
|
+
- official Python docs, not scraped mirrors or mixed-source summaries
|
|
308
|
+
- exact symbol resolution from `objects.inv`
|
|
309
|
+
- Python-version-aware results across 3.10 through 3.14
|
|
310
|
+
- token-efficient section retrieval instead of full-page dumps
|
|
311
|
+
- package-declared PyPI metadata lookup via `lookup_package_docs` for
|
|
312
|
+
documentation, homepage, and source URLs
|
|
313
|
+
- local, read-only runtime behavior with no API keys
|
|
314
|
+
|
|
315
|
+
Use Context7 or a generic docs fetcher when you need broader third-party library
|
|
316
|
+
coverage, arbitrary web pages, or cross-framework research. This server is not a
|
|
317
|
+
universal docs search engine. It is a precise stdlib retrieval tool for AI
|
|
318
|
+
coding agents.
|
|
319
|
+
|
|
320
|
+
## Retrieved docs cache
|
|
321
|
+
|
|
322
|
+
`get_docs` responses are cached across MCP client/server restarts in the
|
|
323
|
+
platform cache directory:
|
|
324
|
+
|
|
325
|
+
```text
|
|
326
|
+
<platform cache dir>/mcp-python-docs/retrieved-docs-cache.sqlite3
|
|
327
|
+
```
|
|
328
|
+
|
|
329
|
+
The cache stores completed `get_docs` results, including page/section content,
|
|
330
|
+
for the resolved Python docs version plus request identity (`slug`, optional
|
|
331
|
+
`anchor`, `max_chars`, and `start_index`). Cache misses fall back to the normal
|
|
332
|
+
local index retrieval path and then write the retrieved result.
|
|
333
|
+
|
|
334
|
+
Cache entries are also scoped to a fingerprint of the local `index.db` file
|
|
335
|
+
(path, size, and modification timestamp). If you rebuild or replace the local
|
|
336
|
+
docs index, older entries are ignored automatically instead of being returned
|
|
337
|
+
for the new index generation. Deleting `retrieved-docs-cache.sqlite3` is safe;
|
|
338
|
+
it only removes cached retrieval results, not the docs index.
|
|
339
|
+
|
|
340
|
+
## PyPI package docs lookup
|
|
341
|
+
|
|
342
|
+
`lookup_package_docs` queries the official PyPI JSON API documented at
|
|
343
|
+
`https://docs.pypi.org/api/json/` (`GET /pypi/<project>/json`) and returns only
|
|
344
|
+
sources declared in that package's PyPI metadata: the PyPI project URL,
|
|
345
|
+
`docs_url`, `home_page`, and allowlisted `project_urls` labels such as
|
|
346
|
+
Documentation, Homepage, Source, and Repository.
|
|
347
|
+
|
|
348
|
+
The tool makes the trust boundary explicit with
|
|
349
|
+
`trust_boundary="pypi-declared-metadata"`. It does not crawl pages, perform web
|
|
350
|
+
search, or silently fall back to unofficial community mirrors.
|
|
351
|
+
|
|
352
|
+
## Diagnostics
|
|
353
|
+
|
|
354
|
+
<!-- PRE-PYPI: remove the GitHub-source doctor invocation and "After PyPI publishing:" lead-in after the first PyPI publish; the post-PyPI code fence below survives -->
|
|
355
|
+
Before PyPI publishing, run `doctor` from the GitHub source package:
|
|
356
|
+
|
|
357
|
+
```bash
|
|
358
|
+
uvx --from git+https://github.com/ayhammouda/python-docs-mcp-server.git python-docs-mcp-server doctor
|
|
359
|
+
```
|
|
360
|
+
|
|
361
|
+
After PyPI publishing:
|
|
362
|
+
<!-- /PRE-PYPI -->
|
|
363
|
+
|
|
364
|
+
Check the local environment:
|
|
365
|
+
|
|
366
|
+
```bash
|
|
367
|
+
uvx python-docs-mcp-server doctor
|
|
368
|
+
```
|
|
369
|
+
|
|
370
|
+
This checks the runtime Python version, SQLite FTS5, cache/index paths, disk
|
|
371
|
+
space, and whether the current interpreter has the `venv`/`ensurepip` support
|
|
372
|
+
needed by `build-index`.
|
|
373
|
+
|
|
374
|
+
<!-- PRE-PYPI: remove the GitHub-source validate-corpus invocation and "After PyPI publishing:" lead-in after the first PyPI publish; the post-PyPI code fence below survives -->
|
|
375
|
+
Before PyPI publishing, validate an existing index from the GitHub source
|
|
376
|
+
package:
|
|
377
|
+
|
|
378
|
+
```bash
|
|
379
|
+
uvx --from git+https://github.com/ayhammouda/python-docs-mcp-server.git python-docs-mcp-server validate-corpus
|
|
380
|
+
```
|
|
381
|
+
|
|
382
|
+
After PyPI publishing:
|
|
383
|
+
<!-- /PRE-PYPI -->
|
|
384
|
+
|
|
385
|
+
Validate an existing index:
|
|
386
|
+
|
|
387
|
+
```bash
|
|
388
|
+
uvx python-docs-mcp-server validate-corpus
|
|
389
|
+
```
|
|
390
|
+
|
|
391
|
+
## Troubleshooting
|
|
392
|
+
|
|
393
|
+
### FTS5 unavailable
|
|
394
|
+
|
|
395
|
+
If you see an error about SQLite FTS5 not being available:
|
|
396
|
+
|
|
397
|
+
**Linux x86-64**
|
|
398
|
+
|
|
399
|
+
Linux x86-64 users can install the optional bundled SQLite package:
|
|
400
|
+
|
|
401
|
+
```bash
|
|
402
|
+
pip install 'python-docs-mcp-server[pysqlite3]'
|
|
403
|
+
```
|
|
404
|
+
|
|
405
|
+
**macOS / Windows / Linux ARM**
|
|
406
|
+
|
|
407
|
+
Install Python from [python.org](https://www.python.org/) or use:
|
|
408
|
+
|
|
409
|
+
```bash
|
|
410
|
+
uv python install
|
|
411
|
+
```
|
|
412
|
+
|
|
413
|
+
### Missing `pythonX.Y-venv` on Debian/Ubuntu
|
|
414
|
+
|
|
415
|
+
If `doctor` reports that build venv support is unavailable, install the venv
|
|
416
|
+
package for the same Python minor version that runs the server:
|
|
417
|
+
|
|
418
|
+
```bash
|
|
419
|
+
sudo apt install python3.12-venv
|
|
420
|
+
```
|
|
421
|
+
|
|
422
|
+
Adjust `3.12` to match the version shown by `doctor`. Without this package,
|
|
423
|
+
`build-index` cannot create the disposable Sphinx environment it uses to build
|
|
424
|
+
JSON documentation content.
|
|
425
|
+
|
|
426
|
+
### Migrating from the pre-rename CLI
|
|
427
|
+
|
|
428
|
+
Earlier development snapshots of this project used the PyPI name
|
|
429
|
+
`mcp-server-python-docs`. The published PyPI project is
|
|
430
|
+
`python-docs-mcp-server`. If your MCP client config still references
|
|
431
|
+
the old name via `uvx`, you will see a `Package not found` error,
|
|
432
|
+
because `uvx` resolves projects by PyPI name.
|
|
433
|
+
|
|
434
|
+
Update your config's `args` from:
|
|
435
|
+
|
|
436
|
+
```json
|
|
437
|
+
"args": ["mcp-server-python-docs"]
|
|
438
|
+
```
|
|
439
|
+
|
|
440
|
+
to:
|
|
441
|
+
|
|
442
|
+
```json
|
|
443
|
+
"args": ["python-docs-mcp-server"]
|
|
444
|
+
```
|
|
445
|
+
|
|
446
|
+
The wheel still installs a legacy `mcp-server-python-docs` console
|
|
447
|
+
script for users who already have the package installed and invoke
|
|
448
|
+
the binary by name on `$PATH`. That script is an alias and will be
|
|
449
|
+
removed in a future release.
|
|
450
|
+
|
|
451
|
+
### `uvx` cache stale
|
|
452
|
+
|
|
453
|
+
If `uvx python-docs-mcp-server` runs an old version:
|
|
454
|
+
|
|
455
|
+
```bash
|
|
456
|
+
uvx --reinstall python-docs-mcp-server
|
|
457
|
+
```
|
|
458
|
+
|
|
459
|
+
Or clear the uv cache:
|
|
460
|
+
|
|
461
|
+
```bash
|
|
462
|
+
uv cache clean python-docs-mcp-server
|
|
463
|
+
```
|
|
464
|
+
|
|
465
|
+
### Claude Desktop on Windows (MSIX)
|
|
466
|
+
|
|
467
|
+
The MSIX-packaged version of Claude Desktop on Windows may have restricted PATH
|
|
468
|
+
access. If `uvx` is not found, specify the full path in your config:
|
|
469
|
+
|
|
470
|
+
<!-- PRE-PYPI: remove the GitHub-source config and the "After PyPI publishing, use:" lead-in after the first PyPI publish; the post-PyPI config fence below survives -->
|
|
471
|
+
```json
|
|
472
|
+
{
|
|
473
|
+
"mcpServers": {
|
|
474
|
+
"python-docs": {
|
|
475
|
+
"command": "C:\\Users\\YOU\\.local\\bin\\uvx.exe",
|
|
476
|
+
"args": [
|
|
477
|
+
"--from",
|
|
478
|
+
"git+https://github.com/ayhammouda/python-docs-mcp-server.git",
|
|
479
|
+
"python-docs-mcp-server"
|
|
480
|
+
]
|
|
481
|
+
}
|
|
482
|
+
}
|
|
483
|
+
}
|
|
484
|
+
```
|
|
485
|
+
|
|
486
|
+
After PyPI publishing, use:
|
|
487
|
+
<!-- /PRE-PYPI -->
|
|
488
|
+
|
|
489
|
+
```json
|
|
490
|
+
{
|
|
491
|
+
"mcpServers": {
|
|
492
|
+
"python-docs": {
|
|
493
|
+
"command": "C:\\Users\\YOU\\.local\\bin\\uvx.exe",
|
|
494
|
+
"args": ["python-docs-mcp-server"]
|
|
495
|
+
}
|
|
496
|
+
}
|
|
497
|
+
}
|
|
498
|
+
```
|
|
499
|
+
|
|
500
|
+
Replace `YOU` with your Windows username. Find the exact path with `where uvx`.
|
|
501
|
+
|
|
502
|
+
### Restart after rebuild
|
|
503
|
+
|
|
504
|
+
After running `build-index`, restart your MCP client so it picks up the new
|
|
505
|
+
database file. The server opens the index read-only at startup and does not
|
|
506
|
+
hot-reload an updated database.
|
|
507
|
+
|
|
508
|
+
On Windows, close the MCP client before rebuilding if the index file is locked.
|
|
509
|
+
|
|
510
|
+
## Contributor workflow
|
|
511
|
+
|
|
512
|
+
For contributor setup and verification:
|
|
513
|
+
|
|
514
|
+
- [`CONTRIBUTING.md`](CONTRIBUTING.md)
|
|
515
|
+
- [`.github/INTEGRATION-TEST.md`](.github/INTEGRATION-TEST.md)
|
|
516
|
+
- [`.github/RELEASE.md`](.github/RELEASE.md)
|
|
517
|
+
|
|
518
|
+
## Support
|
|
519
|
+
|
|
520
|
+
Tested on macOS and Linux. Windows should work, but it is not verified on
|
|
521
|
+
every release.
|
|
522
|
+
|
|
523
|
+
The server requires Python 3.12+ to run. Its generated documentation corpus
|
|
524
|
+
covers Python documentation versions 3.10 through 3.14.
|
|
525
|
+
|
|
526
|
+
## License
|
|
527
|
+
|
|
528
|
+
MIT
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
mcp_server_python_docs/__init__.py,sha256=sUtQT81momSAPMywIkgnR7BZxJHn53rpcjSE3CTAUws,499
|
|
2
|
+
mcp_server_python_docs/__main__.py,sha256=e8O15uUQ6GmnR80hQdRUHJM1aXgY4US_fCqGOXp2_uE,21045
|
|
3
|
+
mcp_server_python_docs/app_context.py,sha256=0HpzQjKjFcbgYhZUvJYuZw9F3xbAckvfYCMKQlWHfZo,1300
|
|
4
|
+
mcp_server_python_docs/detection.py,sha256=JJZ5L90ehxTyS8ebndILpztA960qXCZVO2bgsmz-j-M,2691
|
|
5
|
+
mcp_server_python_docs/diagnostics.py,sha256=FyC6QDFLvozARpYuMnaKfJwaN6BCzVycME_SkNs2YIs,2370
|
|
6
|
+
mcp_server_python_docs/errors.py,sha256=XTOm1raJfxS2adaOPZdwj0SuhpMAXAdjBsF2-zTv_1E,827
|
|
7
|
+
mcp_server_python_docs/models.py,sha256=jtC1TEAOZHBDEfFf8uqsSzC5FKmY06zRrHWzw3HSmsg,6966
|
|
8
|
+
mcp_server_python_docs/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
9
|
+
mcp_server_python_docs/server.py,sha256=-5ib1gZ35iOmJcj98EpwhF22JwbU0YEcL0Sy3mpHTdE,12057
|
|
10
|
+
mcp_server_python_docs/data/synonyms.yaml,sha256=LgJxamZ9QT6Pykva7M1uM8juSd9ybHuv3vUOKrUFMg4,10696
|
|
11
|
+
mcp_server_python_docs/ingestion/__init__.py,sha256=Yd7Jk7hD7XG3eoBVQpYiG94EwJGfI3qXxVCpA8JszYg,66
|
|
12
|
+
mcp_server_python_docs/ingestion/cpython_versions.py,sha256=mEhjuT7q8Bo1aZ-zj6PSqmbq2Bz64g4xj50ttqA4QUU,977
|
|
13
|
+
mcp_server_python_docs/ingestion/inventory.py,sha256=5gQCWOo1tBiQgv-e_A9KR9n2xfP4YAnJrSmb0pFbzwY,5672
|
|
14
|
+
mcp_server_python_docs/ingestion/publish.py,sha256=gra87NgH1i4T92nSwf3sqp4AnKuuzQfrcE7ySnDgcSQ,17247
|
|
15
|
+
mcp_server_python_docs/ingestion/sphinx_json.py,sha256=iXcdBoccY0TcDBC80qa8Zt5LvaSW4NNEFsZgYjHHriE,19252
|
|
16
|
+
mcp_server_python_docs/retrieval/__init__.py,sha256=xSH2dWrIun_Q980ElcoXWBIobTqz0am66-AkEvRo_ck,779
|
|
17
|
+
mcp_server_python_docs/retrieval/budget.py,sha256=kORd1Pt6IxLH95vRE7WBwdwezxvk98deYBgeNLEmyOw,2098
|
|
18
|
+
mcp_server_python_docs/retrieval/query.py,sha256=9rWBvWQG3KwVjCqEqCYKMFgKqswU-O4a1SyJiTzQrjk,6116
|
|
19
|
+
mcp_server_python_docs/retrieval/ranker.py,sha256=GSssXzfaJKEWrCgF_UuTm9-lSzTbYe3cSalsqgq0nUI,11712
|
|
20
|
+
mcp_server_python_docs/services/__init__.py,sha256=UKlaRQYo_cnLOUVf_QieXnHlcnH9ejEa3pYgHhJiG1E,320
|
|
21
|
+
mcp_server_python_docs/services/cache.py,sha256=ADqg89johOJRYZysbes1bEs6nLFrmzS9L5c-Njt1mrU,3199
|
|
22
|
+
mcp_server_python_docs/services/content.py,sha256=7O5XGbR9QWICMxYAd-cp_pPF86tNLcYAMIwyCP_i8dk,5342
|
|
23
|
+
mcp_server_python_docs/services/observability.py,sha256=rwnkIDelNkclHzuwsktGUoU2fzYCuiR1niVRmOwJHJg,4839
|
|
24
|
+
mcp_server_python_docs/services/package_docs.py,sha256=k4yxkWuZEq2aS-w2kIw0Bhl8zzj88AdYGf4xXqW9aKY,5513
|
|
25
|
+
mcp_server_python_docs/services/persistent_cache.py,sha256=KpjutXAVhFPXB-QhgtShxWuTTG0mZWc7j-st7LglfL8,5747
|
|
26
|
+
mcp_server_python_docs/services/search.py,sha256=Pjt4IDfnogWTGYKFJ_4ODbq1xbUZ0ybceD6yj7Ep6lw,4545
|
|
27
|
+
mcp_server_python_docs/services/version.py,sha256=nPkWhksZo7B4QIp-knlSEvVXFmKIcVUq6tWRTJAe5aA,1467
|
|
28
|
+
mcp_server_python_docs/services/version_resolution.py,sha256=rULBoqq97t0ZfSWSy-ecI3wALx5t_3OWuok1hZK8w0w,2643
|
|
29
|
+
mcp_server_python_docs/storage/__init__.py,sha256=YNeNr7FW9Vgvo79oXgKXE3eGP0WwWDqRgTZ7lg7MFW4,62
|
|
30
|
+
mcp_server_python_docs/storage/db.py,sha256=Lys8HN3IvgmNpr_qyocUQghcZnwHf2lz9eq_BFmwi54,5634
|
|
31
|
+
mcp_server_python_docs/storage/schema.sql,sha256=4cXPktPQSLfbjkSjirpf0dA2CphlO9UCIKUxnLiIm_g,5637
|
|
32
|
+
python_docs_mcp_server-0.1.2.dist-info/METADATA,sha256=zPlrnZCtL0lq18iANDS3EMTV0-jcfrh_E_BFvp3saAU,16977
|
|
33
|
+
python_docs_mcp_server-0.1.2.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
|
|
34
|
+
python_docs_mcp_server-0.1.2.dist-info/entry_points.txt,sha256=-1arbtjZhF5mtnJNAh_90UBr1f4AqJxT3Tmfy9p7NMI,142
|
|
35
|
+
python_docs_mcp_server-0.1.2.dist-info/licenses/LICENSE,sha256=-AHGWRwcvoeP4bkY1W2ok_qaI1Mg0Zx2qYgR1k-3CHY,1071
|
|
36
|
+
python_docs_mcp_server-0.1.2.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Aymen Hammouda
|
|
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.
|