lodesman-mcp 0.3.0__tar.gz

lodesman_mcp-0.3.0/.gitignore

@@ -0,0 +1,29 @@
+# Our own working notes, probes, diagnostics and captured logs. Deliberately
+# not published: they are handover documents and speculation, not documentation.
+workdocs/
+
+# Python
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+
+# Downloaded language servers (Roslyn, tsserver, …) and their caches — large,
+# regenerable, machine-specific.
+.solidlsp/
+
+# The Portainer MCP server writes its tool manifest into whatever directory it
+# starts in. Not ours; it reappears after every delete.
+tools.yaml
+
+# Editor/OS noise
+.vscode/
+.idea/
+Thumbs.db
+.DS_Store
+
+# Generated indexes and logs — regenerable, multi-MB, not part of the tool.
+out/
+*.log

lodesman_mcp-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Christer Åkerlund
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lodesman_mcp-0.3.0/NOTICE.md

@@ -0,0 +1,46 @@
+# Third-party notices
+
+Lodesman is MIT-licensed (see `LICENSE`). It bundles the following third-party
+code, which is also MIT-licensed.
+
+## SolidLSP
+
+- **Location in this distribution:** `src/lodesman/_vendor/solidlsp/`
+- **Upstream:** https://github.com/oraios/serena
+- **License:** MIT — full text at `src/lodesman/_vendor/solidlsp/LICENSE`
+- **Copyright:** © 2025–2026 Jain & Panchenko IT-Berater Partnerschaft
+  (Oraios AI) and contributors
+
+SolidLSP is the language-server client library Lodesman is built on. It is
+vendored rather than declared as a dependency because it is not published to
+PyPI independently of the Serena application.
+
+The Serena repository is licensed per component: SolidLSP under MIT, the Serena
+application under GPL-3.0-or-later. **Only SolidLSP is bundled here.** No part
+of the Serena application is included or distributed, so no GPL obligations
+attach to Lodesman. Upstream's own licensing overview states that the SolidLSP
+files "remain MIT-licensed and may be obtained, extracted and used separately
+under MIT terms."
+
+The vendored tree is kept unmodified, with its per-file SPDX headers intact, so
+that it can be re-synced with upstream. Lodesman's own behaviour lives entirely
+outside it.
+
+### OLSP
+
+Some files under `_vendor/solidlsp/lsp_protocol_handler/` are derived from
+[OLSP](https://github.com/predragnikolic/OLSP), © 2023 Предраг Николић, MIT.
+The original notices are retained in those files.
+
+## Runtime dependencies
+
+Installed from PyPI rather than bundled; each carries its own license:
+`pygls`, `lsprotocol`, `psutil`, `pathspec`, `overrides`, `sensai-utils`,
+`filelock`, `requests`, `charset-normalizer`, `typing-extensions`.
+
+## Language servers
+
+Lodesman downloads language servers (Roslyn, typescript-language-server, and
+others) on first use into `~/.solidlsp`. These are **not** bundled and are not
+covered by this notice — each is obtained from its own publisher under its own
+license.

lodesman_mcp-0.3.0/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.5
+Name: lodesman-mcp
+Version: 0.3.0
+Summary: Compiler-grade code intelligence over MCP — a language server's own answers, as agent tools
+Project-URL: Homepage, https://github.com/florpan/lodesman
+Project-URL: Source, https://github.com/florpan/lodesman
+Project-URL: Issues, https://github.com/florpan/lodesman/issues
+Author: Christer Åkerlund
+License-Expression: MIT
+License-File: LICENSE
+License-File: NOTICE.md
+License-File: src/lodesman/_vendor/solidlsp/LICENSE
+Keywords: agent,claude,code-intelligence,language-server,lsp,mcp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: charset-normalizer>=3.4
+Requires-Dist: filelock>=3.16
+Requires-Dist: lsprotocol>=2025.0.0
+Requires-Dist: oslex>=2.0
+Requires-Dist: overrides>=7.7
+Requires-Dist: pathspec>=1.1
+Requires-Dist: psutil>=7.0
+Requires-Dist: pygls>=2.1.1
+Requires-Dist: requests>=2.32
+Requires-Dist: sensai-utils>=1.6
+Requires-Dist: typing-extensions>=4.12
+Description-Content-Type: text/markdown
+
+# Lodesman
+
+**Compiler-grade code intelligence over MCP.** Lodesman puts a real language
+server behind your coding agent's tools, so "who calls this?" is answered by the
+compiler rather than by a text search.
+
+A lodesman is the pilot who comes aboard and steers a ship through waters the
+captain doesn't know. That is the job: an agent dropped into an unfamiliar
+repository, guided by something with local knowledge.
+
+> **Status: alpha.** The tool surface is still growing and not every tool is
+> finished. If you hit something broken, an issue is genuinely useful — see
+> [Status](#status).
+
+## Why
+
+An agent's dominant cost is reading files into context, and a tool that returns
+*coordinates* makes that worse, not better — `Program.cs — L135` forces the
+agent to read the file anyway.
+
+Measured on a real C# repository, answering "what uses `RagQueryService`":
+
+| approach | cost |
+|---|---|
+| read the three files involved | 1745 lines, ~17.7k tokens |
+| the 3 references, with ±6 lines of code each | ~36 lines, ~370 tokens |
+
+**~48× cheaper**, and it is a better answer. So Lodesman's tools return code,
+not locations. A location is a promise of future cost; the code is the answer.
+
+The second reason is correctness. An agent cannot tell a true "no results" from
+a broken query, so a plausible empty answer is the most dangerous thing a
+navigation tool can produce. Lodesman gates every answer on the language server
+actually being ready, and distinguishes "none" from "couldn't tell".
+
+## Install
+
+Requires Python 3.11+.
+
+```bash
+uvx lodesman-mcp          # run without installing
+pipx install lodesman-mcp # or install it
+```
+
+### Wire it into Claude Code
+
+```bash
+claude mcp add lodesman --scope user -- uvx lodesman-mcp
+```
+
+Or, for any MCP client, in the config directly:
+
+```json
+{
+  "mcpServers": {
+    "lodesman": {
+      "command": "uvx",
+      "args": ["lodesman-mcp"]
+    }
+  }
+}
+```
+
+With no arguments Lodesman binds to the working directory it is launched in,
+which is what MCP clients give it. One user-scoped entry therefore works across
+every project — no per-project configuration.
+
+To point it somewhere explicitly:
+
+```bash
+lodesman-mcp /path/to/repo --language csharp
+```
+
+### First run
+
+The language server itself is downloaded on first use into `~/.solidlsp`
+(override with `SOLIDLSP_HOME`). For C# this pulls Roslyn from NuGet and **can
+take several minutes**. Later runs reuse it and start in seconds.
+
+The server process starts immediately; the language server behind it starts
+lazily on the first tool call and is then kept warm for the life of the process.
+That is the whole design: a cold Roslyn costs minutes, a warm one answers in
+milliseconds and tracks your edits incrementally.
+
+## Verify your install
+
+```bash
+python scripts/smoke_test.py /path/to/repo --language csharp
+```
+
+This starts a real language server against a real repository and proves it
+answers the two questions everything else is built on — what symbols are in this
+file, and who references this symbol — with cross-file results the compiler
+agrees with.
+
+## Tools
+
+| tool | what it answers |
+|---|---|
+| `project_info` | which repository this server bound to, and how |
+| `find_symbol` | find a symbol by name anywhere in the project |
+| `find_definition` | where is this defined |
+| `find_references` | what actually uses this, with the surrounding code |
+| `find_implementations` | concrete implementations of an interface or abstract member |
+| `document_symbols` | outline one file: its types, methods and fields |
+| `get_symbol_body` | the full source of one declaration, by name |
+| `explain_symbol` | resolved type, signature and documentation |
+| `blast_radius` | what breaks if this symbol changes |
+| `rename_symbol` | rename everywhere, using the compiler's understanding |
+| `check` | compiler diagnostics for one file, from the warm server |
+
+`blast_radius` and `check` are the two that exist specifically because agents
+edit code they haven't read: one tells you the cost of a change before you make
+it, the other verifies it afterwards without a full build.
+
+## How it binds to a project
+
+One server process serves one repository, chosen at startup: the path you pass,
+or the working directory if you pass nothing.
+
+The language is detected by counting source files under that root and taking the
+majority. Pass `--language` when that guess is wrong — a repo with a TypeScript
+frontend and a C# backend has to be told which one you mean:
+
+```bash
+lodesman-mcp . --language typescript
+```
+
+## Status
+
+Alpha. The tool surface is still growing, and not every tool is finished.
+
+Lodesman inherits SolidLSP's language coverage, and runs wherever its language
+servers do. Not every language and platform combination has been exercised yet,
+so if you try one and it breaks, please
+[open an issue](https://github.com/florpan/lodesman/issues) — a report with the
+language, the OS and the stderr output is the most useful thing you can send.
+Testing help is very welcome.
+
+Known issues are listed here as they are found.
+
+## Built on SolidLSP
+
+The language-server client layer is [SolidLSP](https://github.com/oraios/serena),
+MIT, vendored unmodified under `src/lodesman/_vendor/`. It is bundled rather
+than depended on because it is not published to PyPI independently of the Serena
+application, which is GPL and is **not** included here.
+
+Everything Lodesman does lives outside that tree — the project anchoring, the
+readiness gate, the cross-file indexing wait, symbol ranking, and the decision
+to return code instead of coordinates were all solved by *calling* SolidLSP
+differently, never by editing it. That rule is what keeps re-syncing with
+upstream cheap.
+
+See [NOTICE.md](NOTICE.md) for full attribution.
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+Bundled third-party code, its copyright holders and its license texts are listed
+in [NOTICE.md](NOTICE.md). Everything bundled is MIT-licensed.

lodesman_mcp-0.3.0/README.md

@@ -0,0 +1,162 @@
+# Lodesman
+
+**Compiler-grade code intelligence over MCP.** Lodesman puts a real language
+server behind your coding agent's tools, so "who calls this?" is answered by the
+compiler rather than by a text search.
+
+A lodesman is the pilot who comes aboard and steers a ship through waters the
+captain doesn't know. That is the job: an agent dropped into an unfamiliar
+repository, guided by something with local knowledge.
+
+> **Status: alpha.** The tool surface is still growing and not every tool is
+> finished. If you hit something broken, an issue is genuinely useful — see
+> [Status](#status).
+
+## Why
+
+An agent's dominant cost is reading files into context, and a tool that returns
+*coordinates* makes that worse, not better — `Program.cs — L135` forces the
+agent to read the file anyway.
+
+Measured on a real C# repository, answering "what uses `RagQueryService`":
+
+| approach | cost |
+|---|---|
+| read the three files involved | 1745 lines, ~17.7k tokens |
+| the 3 references, with ±6 lines of code each | ~36 lines, ~370 tokens |
+
+**~48× cheaper**, and it is a better answer. So Lodesman's tools return code,
+not locations. A location is a promise of future cost; the code is the answer.
+
+The second reason is correctness. An agent cannot tell a true "no results" from
+a broken query, so a plausible empty answer is the most dangerous thing a
+navigation tool can produce. Lodesman gates every answer on the language server
+actually being ready, and distinguishes "none" from "couldn't tell".
+
+## Install
+
+Requires Python 3.11+.
+
+```bash
+uvx lodesman-mcp          # run without installing
+pipx install lodesman-mcp # or install it
+```
+
+### Wire it into Claude Code
+
+```bash
+claude mcp add lodesman --scope user -- uvx lodesman-mcp
+```
+
+Or, for any MCP client, in the config directly:
+
+```json
+{
+  "mcpServers": {
+    "lodesman": {
+      "command": "uvx",
+      "args": ["lodesman-mcp"]
+    }
+  }
+}
+```
+
+With no arguments Lodesman binds to the working directory it is launched in,
+which is what MCP clients give it. One user-scoped entry therefore works across
+every project — no per-project configuration.
+
+To point it somewhere explicitly:
+
+```bash
+lodesman-mcp /path/to/repo --language csharp
+```
+
+### First run
+
+The language server itself is downloaded on first use into `~/.solidlsp`
+(override with `SOLIDLSP_HOME`). For C# this pulls Roslyn from NuGet and **can
+take several minutes**. Later runs reuse it and start in seconds.
+
+The server process starts immediately; the language server behind it starts
+lazily on the first tool call and is then kept warm for the life of the process.
+That is the whole design: a cold Roslyn costs minutes, a warm one answers in
+milliseconds and tracks your edits incrementally.
+
+## Verify your install
+
+```bash
+python scripts/smoke_test.py /path/to/repo --language csharp
+```
+
+This starts a real language server against a real repository and proves it
+answers the two questions everything else is built on — what symbols are in this
+file, and who references this symbol — with cross-file results the compiler
+agrees with.
+
+## Tools
+
+| tool | what it answers |
+|---|---|
+| `project_info` | which repository this server bound to, and how |
+| `find_symbol` | find a symbol by name anywhere in the project |
+| `find_definition` | where is this defined |
+| `find_references` | what actually uses this, with the surrounding code |
+| `find_implementations` | concrete implementations of an interface or abstract member |
+| `document_symbols` | outline one file: its types, methods and fields |
+| `get_symbol_body` | the full source of one declaration, by name |
+| `explain_symbol` | resolved type, signature and documentation |
+| `blast_radius` | what breaks if this symbol changes |
+| `rename_symbol` | rename everywhere, using the compiler's understanding |
+| `check` | compiler diagnostics for one file, from the warm server |
+
+`blast_radius` and `check` are the two that exist specifically because agents
+edit code they haven't read: one tells you the cost of a change before you make
+it, the other verifies it afterwards without a full build.
+
+## How it binds to a project
+
+One server process serves one repository, chosen at startup: the path you pass,
+or the working directory if you pass nothing.
+
+The language is detected by counting source files under that root and taking the
+majority. Pass `--language` when that guess is wrong — a repo with a TypeScript
+frontend and a C# backend has to be told which one you mean:
+
+```bash
+lodesman-mcp . --language typescript
+```
+
+## Status
+
+Alpha. The tool surface is still growing, and not every tool is finished.
+
+Lodesman inherits SolidLSP's language coverage, and runs wherever its language
+servers do. Not every language and platform combination has been exercised yet,
+so if you try one and it breaks, please
+[open an issue](https://github.com/florpan/lodesman/issues) — a report with the
+language, the OS and the stderr output is the most useful thing you can send.
+Testing help is very welcome.
+
+Known issues are listed here as they are found.
+
+## Built on SolidLSP
+
+The language-server client layer is [SolidLSP](https://github.com/oraios/serena),
+MIT, vendored unmodified under `src/lodesman/_vendor/`. It is bundled rather
+than depended on because it is not published to PyPI independently of the Serena
+application, which is GPL and is **not** included here.
+
+Everything Lodesman does lives outside that tree — the project anchoring, the
+readiness gate, the cross-file indexing wait, symbol ranking, and the decision
+to return code instead of coordinates were all solved by *calling* SolidLSP
+differently, never by editing it. That rule is what keeps re-syncing with
+upstream cheap.
+
+See [NOTICE.md](NOTICE.md) for full attribution.
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+Bundled third-party code, its copyright holders and its license texts are listed
+in [NOTICE.md](NOTICE.md). Everything bundled is MIT-licensed.

lodesman_mcp-0.3.0/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "lodesman-mcp"
+version = "0.3.0"
+description = "Compiler-grade code intelligence over MCP — a language server's own answers, as agent tools"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE", "NOTICE.md", "src/lodesman/_vendor/solidlsp/LICENSE"]
+authors = [{ name = "Christer Åkerlund" }]
+keywords = ["mcp", "lsp", "language-server", "code-intelligence", "agent", "claude"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Code Generators",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+# Transitive dependencies of the vendored SolidLSP tree, which cannot declare
+# its own since it is not a separate distribution. Lower bounds are the
+# versions Lodesman has actually been run against, not guesses.
+dependencies = [
+    "pygls>=2.1.1",
+    "lsprotocol>=2025.0.0",
+    "psutil>=7.0",
+    "pathspec>=1.1",
+    "overrides>=7.7",
+    "sensai-utils>=1.6",
+    "filelock>=3.16",
+    "oslex>=2.0",
+    "requests>=2.32",
+    "charset-normalizer>=3.4",
+    "typing-extensions>=4.12",
+]
+
+[project.urls]
+Homepage = "https://github.com/florpan/lodesman"
+Source = "https://github.com/florpan/lodesman"
+Issues = "https://github.com/florpan/lodesman/issues"
+
+[project.scripts]
+lodesman-mcp = "lodesman.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/lodesman"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/lodesman", "scripts", "README.md", "LICENSE", "NOTICE.md", "pyproject.toml"]
+
+# The vendored tree ships whole: its language-server manifests and the Solidity
+# preload script are data files the code reads at runtime, not dead weight.
+[tool.hatch.build]
+artifacts = [
+    "src/lodesman/_vendor/solidlsp/**/*.json",
+    "src/lodesman/_vendor/solidlsp/**/*.cjs",
+]