legesher-mcp 0.2.0__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.
- legesher_mcp-0.2.0/LICENSE +190 -0
- legesher_mcp-0.2.0/PKG-INFO +347 -0
- legesher_mcp-0.2.0/README.md +320 -0
- legesher_mcp-0.2.0/legesher_mcp/__init__.py +38 -0
- legesher_mcp-0.2.0/legesher_mcp/__main__.py +6 -0
- legesher_mcp-0.2.0/legesher_mcp/backend.py +905 -0
- legesher_mcp-0.2.0/legesher_mcp/engine.py +432 -0
- legesher_mcp-0.2.0/legesher_mcp/gate.py +153 -0
- legesher_mcp-0.2.0/legesher_mcp/py.typed +0 -0
- legesher_mcp-0.2.0/legesher_mcp/schemas.py +408 -0
- legesher_mcp-0.2.0/legesher_mcp/server.py +751 -0
- legesher_mcp-0.2.0/legesher_mcp/versions.py +58 -0
- legesher_mcp-0.2.0/pyproject.toml +159 -0
- legesher_mcp-0.2.0/tests/__init__.py +1 -0
- legesher_mcp-0.2.0/tests/conftest.py +59 -0
- legesher_mcp-0.2.0/tests/corpus.py +100 -0
- legesher_mcp-0.2.0/tests/interpreter_gaps.py +100 -0
- legesher_mcp-0.2.0/tests/test_backend_seam.py +460 -0
- legesher_mcp-0.2.0/tests/test_clean_environment.py +322 -0
- legesher_mcp-0.2.0/tests/test_engine_unit.py +583 -0
- legesher_mcp-0.2.0/tests/test_entitlement_gate.py +174 -0
- legesher_mcp-0.2.0/tests/test_explain_tool.py +72 -0
- legesher_mcp-0.2.0/tests/test_http_transport.py +283 -0
- legesher_mcp-0.2.0/tests/test_identifier_validation_tool.py +523 -0
- legesher_mcp-0.2.0/tests/test_lookup_tool.py +48 -0
- legesher_mcp-0.2.0/tests/test_map_codebase_tool.py +135 -0
- legesher_mcp-0.2.0/tests/test_prompts.py +41 -0
- legesher_mcp-0.2.0/tests/test_protocol_edges.py +642 -0
- legesher_mcp-0.2.0/tests/test_registry_manifest.py +155 -0
- legesher_mcp-0.2.0/tests/test_resources.py +52 -0
- legesher_mcp-0.2.0/tests/test_round_trip_flag.py +310 -0
- legesher_mcp-0.2.0/tests/test_roundtrip_sweep.py +251 -0
- legesher_mcp-0.2.0/tests/test_security_posture.py +424 -0
- legesher_mcp-0.2.0/tests/test_server_config.py +149 -0
- legesher_mcp-0.2.0/tests/test_server_surface.py +100 -0
- legesher_mcp-0.2.0/tests/test_tool_descriptions.py +85 -0
- legesher_mcp-0.2.0/tests/test_translate_tools.py +145 -0
- legesher_mcp-0.2.0/tests/test_version_support.py +154 -0
|
@@ -0,0 +1,190 @@
|
|
|
1
|
+
Apache License
|
|
2
|
+
Version 2.0, January 2004
|
|
3
|
+
http://www.apache.org/licenses/
|
|
4
|
+
|
|
5
|
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
|
6
|
+
|
|
7
|
+
1. Definitions.
|
|
8
|
+
|
|
9
|
+
"License" shall mean the terms and conditions for use, reproduction,
|
|
10
|
+
and distribution as defined by Sections 1 through 9 of this document.
|
|
11
|
+
|
|
12
|
+
"Licensor" shall mean the copyright owner or entity authorized by
|
|
13
|
+
the copyright owner that is granting the License.
|
|
14
|
+
|
|
15
|
+
"Legal Entity" shall mean the union of the acting entity and all
|
|
16
|
+
other entities that control, are controlled by, or are under common
|
|
17
|
+
control with that entity. For the purposes of this definition,
|
|
18
|
+
"control" means (i) the power, direct or indirect, to cause the
|
|
19
|
+
direction or management of such entity, whether by contract or
|
|
20
|
+
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
|
21
|
+
outstanding shares, or (iii) beneficial ownership of such entity.
|
|
22
|
+
|
|
23
|
+
"You" (or "Your") shall mean an individual or Legal Entity
|
|
24
|
+
exercising permissions granted by this License.
|
|
25
|
+
|
|
26
|
+
"Source" form shall mean the preferred form for making modifications,
|
|
27
|
+
including but not limited to software source code, documentation
|
|
28
|
+
source, and configuration files.
|
|
29
|
+
|
|
30
|
+
"Object" form shall mean any form resulting from mechanical
|
|
31
|
+
transformation or translation of a Source form, including but
|
|
32
|
+
not limited to compiled object code, generated documentation,
|
|
33
|
+
and conversions to other media types.
|
|
34
|
+
|
|
35
|
+
"Work" shall mean the work of authorship, whether in Source or
|
|
36
|
+
Object form, made available under the License, as indicated by a
|
|
37
|
+
copyright notice that is included in or attached to the work
|
|
38
|
+
(an example is provided in the Appendix below).
|
|
39
|
+
|
|
40
|
+
"Derivative Works" shall mean any work, whether in Source or Object
|
|
41
|
+
form, that is based on (or derived from) the Work and for which the
|
|
42
|
+
editorial revisions, annotations, elaborations, or other modifications
|
|
43
|
+
represent, as a whole, an original work of authorship. For the purposes
|
|
44
|
+
of this License, Derivative Works shall not include works that remain
|
|
45
|
+
separable from, or merely link (or bind by name) to the interfaces of,
|
|
46
|
+
the Work and Derivative Works thereof.
|
|
47
|
+
|
|
48
|
+
"Contribution" shall mean any work of authorship, including
|
|
49
|
+
the original version of the Work and any modifications or additions
|
|
50
|
+
to that Work or Derivative Works thereof, that is intentionally
|
|
51
|
+
submitted to the Licensor for inclusion in the Work by the copyright owner
|
|
52
|
+
or by an individual or Legal Entity authorized to submit on behalf of
|
|
53
|
+
the copyright owner. For the purposes of this definition, "submitted"
|
|
54
|
+
means any form of electronic, verbal, or written communication sent
|
|
55
|
+
to the Licensor or its representatives, including but not limited to
|
|
56
|
+
communication on electronic mailing lists, source code control systems,
|
|
57
|
+
and issue tracking systems that are managed by, or on behalf of, the
|
|
58
|
+
Licensor for the purpose of discussing and improving the Work, but
|
|
59
|
+
excluding communication that is conspicuously marked or otherwise
|
|
60
|
+
designated in writing by the copyright owner as "Not a Contribution."
|
|
61
|
+
|
|
62
|
+
"Contributor" shall mean Licensor and any individual or Legal Entity
|
|
63
|
+
on behalf of whom a Contribution has been received by the Licensor and
|
|
64
|
+
subsequently incorporated within the Work.
|
|
65
|
+
|
|
66
|
+
2. Grant of Copyright License. Subject to the terms and conditions of
|
|
67
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
68
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
69
|
+
copyright license to reproduce, prepare Derivative Works of,
|
|
70
|
+
publicly display, publicly perform, sublicense, and distribute the
|
|
71
|
+
Work and such Derivative Works in Source or Object form.
|
|
72
|
+
|
|
73
|
+
3. Grant of Patent License. Subject to the terms and conditions of
|
|
74
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
75
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
76
|
+
(except as stated in this section) patent license to make, have made,
|
|
77
|
+
use, offer to sell, sell, import, and otherwise transfer the Work,
|
|
78
|
+
where such license applies only to those patent claims licensable
|
|
79
|
+
by such Contributor that are necessarily infringed by their
|
|
80
|
+
Contribution(s) alone or by combination of their Contribution(s)
|
|
81
|
+
with the Work to which such Contribution(s) was submitted. If You
|
|
82
|
+
institute patent litigation against any entity (including a
|
|
83
|
+
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
|
84
|
+
or a Contribution incorporated within the Work constitutes direct
|
|
85
|
+
or contributory patent infringement, then any patent licenses
|
|
86
|
+
granted to You under this License for that Work shall terminate
|
|
87
|
+
as of the date such litigation is filed.
|
|
88
|
+
|
|
89
|
+
4. Redistribution. You may reproduce and distribute copies of the
|
|
90
|
+
Work or Derivative Works thereof in any medium, with or without
|
|
91
|
+
modifications, and in Source or Object form, provided that You
|
|
92
|
+
meet the following conditions:
|
|
93
|
+
|
|
94
|
+
(a) You must give any other recipients of the Work or
|
|
95
|
+
Derivative Works a copy of this License; and
|
|
96
|
+
|
|
97
|
+
(b) You must cause any modified files to carry prominent notices
|
|
98
|
+
stating that You changed the files; and
|
|
99
|
+
|
|
100
|
+
(c) You must retain, in the Source form of any Derivative Works
|
|
101
|
+
that You distribute, all copyright, patent, trademark, and
|
|
102
|
+
attribution notices from the Source form of the Work,
|
|
103
|
+
excluding those notices that do not pertain to any part of
|
|
104
|
+
the Derivative Works; and
|
|
105
|
+
|
|
106
|
+
(d) If the Work includes a "NOTICE" text file as part of its
|
|
107
|
+
distribution, then any Derivative Works that You distribute must
|
|
108
|
+
include a readable copy of the attribution notices contained
|
|
109
|
+
within such NOTICE file, excluding any notices that do not
|
|
110
|
+
pertain to any part of the Derivative Works, in at least one
|
|
111
|
+
of the following places: within a NOTICE text file distributed
|
|
112
|
+
as part of the Derivative Works; within the Source form or
|
|
113
|
+
documentation, if provided along with the Derivative Works; or,
|
|
114
|
+
within a display generated by the Derivative Works, if and
|
|
115
|
+
wherever such third-party notices normally appear. The contents
|
|
116
|
+
of the NOTICE file are for informational purposes only and
|
|
117
|
+
do not modify the License. You may add Your own attribution
|
|
118
|
+
notices within Derivative Works that You distribute, alongside
|
|
119
|
+
or as an addendum to the NOTICE text from the Work, provided
|
|
120
|
+
that such additional attribution notices cannot be construed
|
|
121
|
+
as modifying the License.
|
|
122
|
+
|
|
123
|
+
You may add Your own copyright statement to Your modifications and
|
|
124
|
+
may provide additional or different license terms and conditions
|
|
125
|
+
for use, reproduction, or distribution of Your modifications, or
|
|
126
|
+
for any such Derivative Works as a whole, provided Your use,
|
|
127
|
+
reproduction, and distribution of the Work otherwise complies with
|
|
128
|
+
the conditions stated in this License.
|
|
129
|
+
|
|
130
|
+
5. Submission of Contributions. Unless You explicitly state otherwise,
|
|
131
|
+
any Contribution intentionally submitted for inclusion in the Work
|
|
132
|
+
by You to the Licensor shall be under the terms and conditions of
|
|
133
|
+
this License, without any additional terms or conditions.
|
|
134
|
+
Notwithstanding the above, nothing herein shall supersede or modify
|
|
135
|
+
the terms of any separate license agreement you may have executed
|
|
136
|
+
with Licensor regarding such Contributions.
|
|
137
|
+
|
|
138
|
+
6. Trademarks. This License does not grant permission to use the trade
|
|
139
|
+
names, trademarks, service marks, or product names of the Licensor,
|
|
140
|
+
except as required for reasonable and customary use in describing the
|
|
141
|
+
origin of the Work and reproducing the content of the NOTICE file.
|
|
142
|
+
|
|
143
|
+
7. Disclaimer of Warranty. Unless required by applicable law or
|
|
144
|
+
agreed to in writing, Licensor provides the Work (and each
|
|
145
|
+
Contributor provides its Contributions) on an "AS IS" BASIS,
|
|
146
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
|
147
|
+
implied, including, without limitation, any warranties or conditions
|
|
148
|
+
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
|
149
|
+
PARTICULAR PURPOSE. You are solely responsible for determining the
|
|
150
|
+
appropriateness of using or redistributing the Work and assume any
|
|
151
|
+
risks associated with Your exercise of permissions under this License.
|
|
152
|
+
|
|
153
|
+
8. Limitation of Liability. In no event and under no legal theory,
|
|
154
|
+
whether in tort (including negligence), contract, or otherwise,
|
|
155
|
+
unless required by applicable law (such as deliberate and grossly
|
|
156
|
+
negligent acts) or agreed to in writing, shall any Contributor be
|
|
157
|
+
liable to You for damages, including any direct, indirect, special,
|
|
158
|
+
incidental, or consequential damages of any character arising as a
|
|
159
|
+
result of this License or out of the use or inability to use the
|
|
160
|
+
Work (including but not limited to damages for loss of goodwill,
|
|
161
|
+
work stoppage, computer failure or malfunction, or any and all
|
|
162
|
+
other commercial damages or losses), even if such Contributor
|
|
163
|
+
has been advised of the possibility of such damages.
|
|
164
|
+
|
|
165
|
+
9. Accepting Warranty or Additional Liability. While redistributing
|
|
166
|
+
the Work or Derivative Works thereof, You may choose to offer,
|
|
167
|
+
and charge a fee for, acceptance of support, warranty, indemnity,
|
|
168
|
+
or other liability obligations and/or rights consistent with this
|
|
169
|
+
License. However, in accepting such obligations, You may act only
|
|
170
|
+
on Your own behalf and on Your sole responsibility, not on behalf
|
|
171
|
+
of any other Contributor, and only if You agree to indemnify,
|
|
172
|
+
defend, and hold each Contributor harmless for any liability
|
|
173
|
+
incurred by, or claims asserted against, such Contributor by reason
|
|
174
|
+
of your accepting any such warranty or additional liability.
|
|
175
|
+
|
|
176
|
+
END OF TERMS AND CONDITIONS
|
|
177
|
+
|
|
178
|
+
Copyright 2025-2026 Madison (Pfaff) Edgar and Legesher Contributors
|
|
179
|
+
|
|
180
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
181
|
+
you may not use this file except in compliance with the License.
|
|
182
|
+
You may obtain a copy of the License at
|
|
183
|
+
|
|
184
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
185
|
+
|
|
186
|
+
Unless required by applicable law or agreed to in writing, software
|
|
187
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
188
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
189
|
+
See the License for the specific language governing permissions and
|
|
190
|
+
limitations under the License.
|
|
@@ -0,0 +1,347 @@
|
|
|
1
|
+
Metadata-Version: 2.1
|
|
2
|
+
Name: legesher-mcp
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: Model Context Protocol (MCP) server for the Legesher translation engine
|
|
5
|
+
Keywords: legesher,mcp,model-context-protocol,python,translation,i18n,localization,multilingual,language-packs,round-trip
|
|
6
|
+
Author-Email: "Madison (Pfaff) Edgar" <7844510+madiedgar@users.noreply.github.com>
|
|
7
|
+
License: Apache-2.0
|
|
8
|
+
Classifier: Development Status :: 3 - Alpha
|
|
9
|
+
Classifier: Intended Audience :: Developers
|
|
10
|
+
Classifier: License :: OSI Approved :: Apache Software License
|
|
11
|
+
Classifier: Programming Language :: Python :: 3
|
|
12
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
16
|
+
Project-URL: Homepage, https://legesher.io
|
|
17
|
+
Project-URL: Documentation, https://docs.legesher.io
|
|
18
|
+
Project-URL: Repository, https://github.com/legesher/legesher
|
|
19
|
+
Project-URL: Changelog, https://github.com/legesher/legesher/blob/main/libs/mcp/CHANGELOG.md
|
|
20
|
+
Project-URL: Issues, https://github.com/legesher/legesher/issues
|
|
21
|
+
Requires-Python: <4.0,>=3.10
|
|
22
|
+
Requires-Dist: mcp<2.0.0,>=1.16.0
|
|
23
|
+
Requires-Dist: pydantic>=2.5.0
|
|
24
|
+
Requires-Dist: legesher-core<1.0.0,>=0.23.0
|
|
25
|
+
Requires-Dist: legesher-i18n<1.0.0,>=0.22.0
|
|
26
|
+
Description-Content-Type: text/markdown
|
|
27
|
+
|
|
28
|
+
# legesher-mcp
|
|
29
|
+
|
|
30
|
+
<!-- mcp-name: io.github.legesher/legesher-mcp -->
|
|
31
|
+
|
|
32
|
+
The Legesher [Model Context Protocol](https://modelcontextprotocol.io) server:
|
|
33
|
+
the engine's translation capability inside every MCP-capable client — Claude,
|
|
34
|
+
IDE assistants, agent frameworks — as six coarse, task-shaped tools.
|
|
35
|
+
|
|
36
|
+
**Using the MCP server is free forever (Apache-2.0).** The local server runs
|
|
37
|
+
entirely against the locally installed Legesher engine: it needs no account,
|
|
38
|
+
and every tool call is served locally. Optional usage telemetry is planned
|
|
39
|
+
and will be off unless you turn it on; the Privacy section below says
|
|
40
|
+
exactly what it would send. Some capabilities require a Legesher account on
|
|
41
|
+
the hosted instance. What the server does is defined by this open package
|
|
42
|
+
and nothing else.
|
|
43
|
+
|
|
44
|
+
## Tools
|
|
45
|
+
|
|
46
|
+
| Tool | What it does |
|
|
47
|
+
| --- | --- |
|
|
48
|
+
| `translate_to_native` | Translate Python source into your natural language. Accepts complete files and fragments alike — no separate snippet mode. |
|
|
49
|
+
| `translate_to_source` | Translate native-language code back to English-keyword Python — the form the interpreter, the toolchain, and upstream collaborators use. |
|
|
50
|
+
| `explain_in_language` | Return the *engine facts* an assistant needs to explain code in your language: construct-by-construct keyword mappings, a static validation result, and (optionally) the translated source. The model writes the prose; the tool never does. |
|
|
51
|
+
| `lookup_keyword_mapping` | Quick-reference lookup: how do specific terms (or the full mapping) render in a language. |
|
|
52
|
+
| `map_existing_codebase` | The legibility report: given a set of files, what would translating this codebase into a language look like — per-file coverage, unmapped constructs, and optionally the translated files. |
|
|
53
|
+
| `validate_identifier_translations` | Check proposed identifier translations before recording them: malformed identifiers, unsafe text, names the pack has reserved, drift (one concept, two terms) and collision (two concepts, one term) — against both your existing glossary and the rest of the batch. Comparison is NFKC+casefold, so case variants and decomposed forms count as the same term. Returns the conflict-free subset, NFC-normalized and ready to record. |
|
|
54
|
+
|
|
55
|
+
Notes on shape, straight from the design:
|
|
56
|
+
|
|
57
|
+
- Translation X→Y **pivots through English** (packs are authored against
|
|
58
|
+
English). The engine has no direct X→Y path; when the pivot is taken the
|
|
59
|
+
result says so via `pivoted: true` rather than failing.
|
|
60
|
+
- Validation is **static only** — `compile()`, never `exec()` — submitted
|
|
61
|
+
code is parsed, never executed.
|
|
62
|
+
- Error results carry a machine code (`unsupported_language`,
|
|
63
|
+
`language_pack_not_found`, `invalid_source`) and a generic message: no
|
|
64
|
+
stack traces, no filesystem paths, no echoed source.
|
|
65
|
+
|
|
66
|
+
## Resources
|
|
67
|
+
|
|
68
|
+
| URI | Contents |
|
|
69
|
+
| --- | --- |
|
|
70
|
+
| `legesher://languages` | The language catalog with pack availability. |
|
|
71
|
+
| `legesher://languages/{lang}/terms` | The full term dictionary (keywords, builtins, exceptions, reserved words) for one language, at the default Python version. |
|
|
72
|
+
| `legesher://languages/{lang}/terms/{python_version}` | The same dictionary pinned to a Python version, for callers on a grammar other than the default. |
|
|
73
|
+
|
|
74
|
+
## Prompts
|
|
75
|
+
|
|
76
|
+
- `explain-in` — scaffolds "explain the selected code in {language}",
|
|
77
|
+
steering the model to `explain_in_language` first and keeping engine facts
|
|
78
|
+
distinct from narration.
|
|
79
|
+
- `translate-review` — walks a source/translated pair: translate, validate,
|
|
80
|
+
then summarize what changed and what did not map.
|
|
81
|
+
- `legibility-report` — drives `map_existing_codebase` over pasted files and
|
|
82
|
+
renders the coverage report as a stakeholder-readable summary.
|
|
83
|
+
|
|
84
|
+
## Install
|
|
85
|
+
|
|
86
|
+
The server needs the Legesher engine. Every language pack ships inside
|
|
87
|
+
`legesher-i18n`, so nothing else is installed:
|
|
88
|
+
|
|
89
|
+
```bash
|
|
90
|
+
# The server (pulls legesher-core and legesher-i18n, packs included)
|
|
91
|
+
uvx legesher-mcp
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
Inside the monorepo workspace every shipped pack is already installed:
|
|
95
|
+
|
|
96
|
+
```bash
|
|
97
|
+
uv run legesher-mcp
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
The server is quiet by default (log level WARNING). For troubleshooting,
|
|
101
|
+
set `LEGESHER_MCP_LOG_LEVEL` (`DEBUG`, `INFO`, `WARNING`, `ERROR`,
|
|
102
|
+
`CRITICAL`); unrecognized values fall back to the quiet default. GUI
|
|
103
|
+
clients do not run your shell, so the variable has to go in the client's
|
|
104
|
+
own config — every block below shows where.
|
|
105
|
+
|
|
106
|
+
## Client configuration
|
|
107
|
+
|
|
108
|
+
### Claude Desktop
|
|
109
|
+
|
|
110
|
+
`claude_desktop_config.json` (Settings → Developer → Edit Config):
|
|
111
|
+
|
|
112
|
+
```json
|
|
113
|
+
{
|
|
114
|
+
"mcpServers": {
|
|
115
|
+
"legesher": {
|
|
116
|
+
"command": "uvx",
|
|
117
|
+
"args": ["legesher-mcp"],
|
|
118
|
+
"env": { "LEGESHER_MCP_LOG_LEVEL": "DEBUG" }
|
|
119
|
+
}
|
|
120
|
+
}
|
|
121
|
+
}
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
### Claude Code
|
|
125
|
+
|
|
126
|
+
```bash
|
|
127
|
+
claude mcp add legesher -- uvx legesher-mcp
|
|
128
|
+
|
|
129
|
+
# with troubleshooting logs
|
|
130
|
+
claude mcp add legesher --env LEGESHER_MCP_LOG_LEVEL=DEBUG -- uvx legesher-mcp
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
### Cursor
|
|
134
|
+
|
|
135
|
+
`.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):
|
|
136
|
+
|
|
137
|
+
```json
|
|
138
|
+
{
|
|
139
|
+
"mcpServers": {
|
|
140
|
+
"legesher": {
|
|
141
|
+
"command": "uvx",
|
|
142
|
+
"args": ["legesher-mcp"],
|
|
143
|
+
"env": { "LEGESHER_MCP_LOG_LEVEL": "DEBUG" }
|
|
144
|
+
}
|
|
145
|
+
}
|
|
146
|
+
}
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
### VS Code
|
|
150
|
+
|
|
151
|
+
`.vscode/mcp.json` (workspace) or the user-level `mcp.json` (Command
|
|
152
|
+
Palette: *MCP: Open User Configuration*):
|
|
153
|
+
|
|
154
|
+
```json
|
|
155
|
+
{
|
|
156
|
+
"servers": {
|
|
157
|
+
"legesher": {
|
|
158
|
+
"type": "stdio",
|
|
159
|
+
"command": "uvx",
|
|
160
|
+
"args": ["legesher-mcp"],
|
|
161
|
+
"env": { "LEGESHER_MCP_LOG_LEVEL": "DEBUG" }
|
|
162
|
+
}
|
|
163
|
+
}
|
|
164
|
+
}
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
### Zed
|
|
168
|
+
|
|
169
|
+
`settings.json` → `context_servers`:
|
|
170
|
+
|
|
171
|
+
```json
|
|
172
|
+
{
|
|
173
|
+
"context_servers": {
|
|
174
|
+
"legesher": {
|
|
175
|
+
"command": {
|
|
176
|
+
"path": "uvx",
|
|
177
|
+
"args": ["legesher-mcp"],
|
|
178
|
+
"env": { "LEGESHER_MCP_LOG_LEVEL": "DEBUG" }
|
|
179
|
+
}
|
|
180
|
+
}
|
|
181
|
+
}
|
|
182
|
+
}
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
The `env` block is optional in every case — drop it to keep the quiet
|
|
186
|
+
default.
|
|
187
|
+
|
|
188
|
+
## Serving over HTTP (self-host / single-user)
|
|
189
|
+
|
|
190
|
+
stdio is the default and what every client config above spawns. The same
|
|
191
|
+
server also speaks the MCP streamable HTTP transport, for running it as a
|
|
192
|
+
long-lived local service or on a machine you control:
|
|
193
|
+
|
|
194
|
+
```bash
|
|
195
|
+
legesher-mcp --transport streamable-http # 127.0.0.1:8000/mcp
|
|
196
|
+
legesher-mcp --transport streamable-http --port 9000
|
|
197
|
+
legesher-mcp --transport streamable-http --host 192.0.2.7
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
The posture, deliberately:
|
|
201
|
+
|
|
202
|
+
- **Loopback by default, never a wildcard.** `--host` defaults to
|
|
203
|
+
`127.0.0.1`, and wildcard binds (`0.0.0.0`, `::`) are refused: this
|
|
204
|
+
entry ships **no authentication**, so it binds exactly one interface
|
|
205
|
+
you name. To serve beyond a machine you trust end to end, put your own
|
|
206
|
+
auth in front (below).
|
|
207
|
+
- **Stateless, plain JSON.** Every request is self-contained — no
|
|
208
|
+
server-held session — and responses are `application/json`, not SSE.
|
|
209
|
+
- **`Origin` validated when present.** A browser page from another
|
|
210
|
+
origin (the DNS-rebinding vector) is rejected with 403; the allowlist
|
|
211
|
+
derives from the bound interface. MCP clients that send no `Origin`
|
|
212
|
+
header are unaffected.
|
|
213
|
+
|
|
214
|
+
Embedding instead of running: `legesher_mcp.server.create_server()` builds
|
|
215
|
+
the complete server from a `Backend` and an entitlement gate, and
|
|
216
|
+
`create_http_app()` returns it as an ASGI app to mount behind your own
|
|
217
|
+
middleware (TLS, auth, request context for the gate — see
|
|
218
|
+
`legesher_mcp.gate.request_context`). The gate is **default-open**: no
|
|
219
|
+
deployment code here installs one, gated tools always stay listed, and an
|
|
220
|
+
unentitled call answers with an actionable message rather than an opaque
|
|
221
|
+
failure. `validate_identifier_translations` is permanently free by
|
|
222
|
+
construction.
|
|
223
|
+
|
|
224
|
+
## Making agent sessions stay localized
|
|
225
|
+
|
|
226
|
+
The server is the deterministic half; two shipped artifacts carry the
|
|
227
|
+
policy and playbook half for agent sessions:
|
|
228
|
+
|
|
229
|
+
- **`templates/AGENTS-template.md`** — the language-policy declaration.
|
|
230
|
+
Copy it into a repository root as `AGENTS.md`, fill in the declared
|
|
231
|
+
language, and every `AGENTS.md`-reading agent (Codex, Cursor, Claude
|
|
232
|
+
Code, Antigravity, Windsurf) picks up the same eight rules: write
|
|
233
|
+
natively, never hand-translate keywords, one-concept-one-term naming
|
|
234
|
+
via the project glossary, and the byte-identical round-trip guarantee.
|
|
235
|
+
The file is the *declaration*; long sessions evict rules files from
|
|
236
|
+
context, which is exactly why the deterministic tools — not the file —
|
|
237
|
+
are the *guarantee*.
|
|
238
|
+
- **`skills/legesher-localized-code/`** — the stable-knowledge skill
|
|
239
|
+
([Agent Skills](https://agentskills.io) format: portable across Claude
|
|
240
|
+
Code, Claude apps, and the API). It teaches the mental model
|
|
241
|
+
(run form ↔ native, deterministic vs fuzzy layers), which tool to call
|
|
242
|
+
when, the write → round-trip → validate workflow, and the naming
|
|
243
|
+
discipline. Claude Code: copy the directory into your project's
|
|
244
|
+
`.claude/skills/`. Skills carry the *stable* playbook; the MCP server
|
|
245
|
+
stays the live surface — that split is deliberate.
|
|
246
|
+
|
|
247
|
+
## Privacy
|
|
248
|
+
|
|
249
|
+
- **No telemetry in this version.** The server sends nothing. A coming
|
|
250
|
+
release adds an optional usage report so the maintainers can see which
|
|
251
|
+
tools are used and how often; earlier versions of this README promised
|
|
252
|
+
that the server would never emit telemetry, and that promise is
|
|
253
|
+
withdrawn. When the report ships:
|
|
254
|
+
- It is **off by default**. Nothing is sent unless you set
|
|
255
|
+
`LEGESHER_MCP_TELEMETRY=on` in the server's environment (the `env`
|
|
256
|
+
block or `--env` flag of your client config, as in the examples
|
|
257
|
+
above).
|
|
258
|
+
- `DO_NOT_TRACK=1` or `LEGESHER_TELEMETRY_DISABLED=1` always wins and
|
|
259
|
+
overrides every other setting.
|
|
260
|
+
- It sends only: tool name, call count, error class, server and engine
|
|
261
|
+
versions, and a random install id (kept per install so repeated
|
|
262
|
+
reports count once; not derived from your machine, account or code).
|
|
263
|
+
Never source code, file contents, identifiers, translated text,
|
|
264
|
+
prompts, file paths, or anything that identifies you personally.
|
|
265
|
+
- It runs off the request path: a tool call never waits on it or fails
|
|
266
|
+
because of it, and a report that cannot be delivered is dropped.
|
|
267
|
+
- It never touches the MCP stdio stream.
|
|
268
|
+
- **No network on a tool call.** Every tool call is served by the local
|
|
269
|
+
engine. The usage report above, once it ships and only if you enable
|
|
270
|
+
it, is the only outbound traffic this package is designed to initiate.
|
|
271
|
+
- **Your code is not stored.** Submitted source is processed in memory; file *paths*
|
|
272
|
+
passed to `map_existing_codebase` are report labels — echoed back to you,
|
|
273
|
+
never logged, never used to touch the filesystem. This is why
|
|
274
|
+
`validate_identifier_translations` takes your glossary as *content* and
|
|
275
|
+
hands back the accepted entries rather than saving them: recording is
|
|
276
|
+
yours to do, whether that is `.legesher/identifier_map.json` in your repo
|
|
277
|
+
or the `legesher` CLI, which already maintains that file. A durable
|
|
278
|
+
glossary that outlives the session and is shared across repos and
|
|
279
|
+
teammates is a system of record, and belongs behind the hosted API — not
|
|
280
|
+
in a local subprocess.
|
|
281
|
+
- **Declared, not just claimed.** All six tools carry MCP annotations
|
|
282
|
+
saying so: `readOnlyHint: true`, `idempotentHint: true`,
|
|
283
|
+
`destructiveHint: false`, `openWorldHint: false`. Clients that read the
|
|
284
|
+
hints (Claude Code among them) can reduce or skip approval prompts,
|
|
285
|
+
because no tool call writes a file, executes submitted code (validation
|
|
286
|
+
is `compile()` only), or opens a socket. A surface-lock test asserts the
|
|
287
|
+
annotations, so a future tool that *does* any of those has to change them
|
|
288
|
+
deliberately.
|
|
289
|
+
|
|
290
|
+
## Development
|
|
291
|
+
|
|
292
|
+
```bash
|
|
293
|
+
cd libs/mcp
|
|
294
|
+
uv run pytest # the per-commit suite (every tool, through MCP)
|
|
295
|
+
uv run pytest -m scheduled # release-tier: all-packs sweep + wheel spawn
|
|
296
|
+
uv run ruff check . # lint
|
|
297
|
+
uv run mypy legesher_mcp # types
|
|
298
|
+
```
|
|
299
|
+
|
|
300
|
+
Two test tiers. The default run exercises every tool through a real MCP
|
|
301
|
+
client session and stays fast. The `scheduled` tier is excluded from it and
|
|
302
|
+
run before a release:
|
|
303
|
+
|
|
304
|
+
- **All-packs round-trip sweep** — the byte-identical guarantee across every
|
|
305
|
+
installed pack and the whole construct corpus (the per-commit run samples
|
|
306
|
+
three packs). Known engine/pack failures are listed as strict xfails in
|
|
307
|
+
`tests/test_roundtrip_sweep.py`, so a fix announces itself.
|
|
308
|
+
- **Clean-environment spawn** — builds the wheels, installs them into a
|
|
309
|
+
fresh virtualenv in an empty directory, and drives a stdio session with a
|
|
310
|
+
stripped environment. It is the only test that exercises the artifact the
|
|
311
|
+
way a host actually starts it: outside the workspace, with no
|
|
312
|
+
`PYTHONPATH` and no repo checkout.
|
|
313
|
+
|
|
314
|
+
**It gates the release.** `release-mcp.yml` runs `make test-mcp-scheduled`
|
|
315
|
+
before the version step, so a failure means no version bump, no tag, and
|
|
316
|
+
no GitHub release — nothing to un-publish. Run it locally with
|
|
317
|
+
`make test-mcp-scheduled` before you expect a release to go out.
|
|
318
|
+
|
|
319
|
+
Scope, so the guarantee isn't overread: it gates *cutting a version*. The
|
|
320
|
+
push to a package index is the `mcp` target of `publish-pypi.yml`, which is
|
|
321
|
+
dispatch-only and runs after `foundation` has reached the same index
|
|
322
|
+
(CORE-626).
|
|
323
|
+
|
|
324
|
+
## Versioning
|
|
325
|
+
|
|
326
|
+
`legesher-mcp` releases on its own train, independent of the foundation
|
|
327
|
+
suite: tags are `mcp-v{version}`, cut by `release-mcp.yml` when something
|
|
328
|
+
under `libs/mcp/` lands on `main`. The version in `pyproject.toml` is the
|
|
329
|
+
single source — `__version__` reads it back through `importlib.metadata`, so
|
|
330
|
+
the `initialize` handshake cannot report a number the wheel does not have.
|
|
331
|
+
|
|
332
|
+
Pre-1.0, a breaking change bumps the minor (`0.1.0` → `0.2.0`);
|
|
333
|
+
`major_on_zero` is off, so reaching 1.0.0 is a deliberate decision rather
|
|
334
|
+
than a side effect of one commit.
|
|
335
|
+
|
|
336
|
+
## Listings
|
|
337
|
+
|
|
338
|
+
`server.json` is the manifest the official MCP registry reads, and the
|
|
339
|
+
`mcp-name` comment at the top of this README is how that registry confirms
|
|
340
|
+
the PyPI package belongs to the listing. `docs/registry-listings.md` holds
|
|
341
|
+
the canonical listing copy and what each directory reads, so every listing
|
|
342
|
+
says the same thing. `tests/test_registry_manifest.py` pins the manifest to
|
|
343
|
+
this package's name, version and environment variables.
|
|
344
|
+
|
|
345
|
+
## License
|
|
346
|
+
|
|
347
|
+
Apache-2.0. See [LICENSE](LICENSE).
|