forge-cpp-mcp 0.2.1__tar.gz → 0.2.3__tar.gz

{forge_cpp_mcp-0.2.1 → forge_cpp_mcp-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: forge-cpp-mcp
-Version: 0.2.1
+Version: 0.2.3
 Summary: A safe MCP server for structured C++ project development workflows.
 Project-URL: Homepage, https://github.com/hardened-steel/ForgeMCP
 Project-URL: Repository, https://github.com/hardened-steel/ForgeMCP
@@ -10,6 +10,7 @@ Author: ForgeMCP contributors
 License-Expression: MIT
 License-File: LICENSE
 Requires-Python: >=3.13
+Requires-Dist: markdown-it-py>=4.0
 Requires-Dist: mcp[cli]==2.1.1
 Requires-Dist: pydantic>=2.13
 Requires-Dist: regex>=2024.11.6
@@ -56,8 +57,12 @@ debugger modules are planned.
   toolsets as markdown, querying available versions for details, with completion
   for retained toolset IDs.
 
-The tools remain useful in clients without MCP Apps support because the Python SDK
-serializes their typed results into both text `content` and `structuredContent`.
+Every tool returns readable English plain text in `content` alongside its typed
+`structuredContent`. Trees use branch characters, source excerpts use line numbers,
+and diagnostics use compiler-style messages. Text does not include Markdown
+formatting or Workspace provider resource links; the structured data retains those
+links for widgets. Clients decide how to display the text and may prefer structured
+data when supplying results to a model.
 
 All widgets share a compact console style with a fixed 420px height and adapt to the
 host width. The move confirmation uses only two rows, source and destination.
@@ -88,7 +93,7 @@ and install it in a virtual environment:
 
 ```powershell
 python -m venv .venv
-.\.venv\Scripts\python.exe -m pip install .\forge_cpp_mcp-0.2.1-py3-none-any.whl
+.\.venv\Scripts\python.exe -m pip install .\forge_cpp_mcp-0.2.3-py3-none-any.whl
 .\.venv\Scripts\forgemcp.exe --help
 ```
 
@@ -100,7 +105,7 @@ The distribution name is `forge-cpp-mcp`; the Python module and server command a
 After the package is published to PyPI, the install command can instead be:
 
 ```powershell
-.\.venv\Scripts\python.exe -m pip install forge-cpp-mcp==0.2.1
+.\.venv\Scripts\python.exe -m pip install forge-cpp-mcp==0.2.3
 ```
 
 ## Setup from source
@@ -163,13 +168,27 @@ add the `forgemcp` entry to it rather than replacing the file. Restart the clien
 after editing its configuration. Check the connection with `codex mcp list` or
 `claude mcp get forgemcp`, respectively.
 
+To require agents to use ForgeMCP for supported operations, append the
+[example agent instructions](examples/mcp-clients/agent-instructions.md) to your
+project's `AGENTS.md` (Codex) or `CLAUDE.md` (Claude Code). The same block works
+for both clients and requires evidence of an unsupported operation, tool failure,
+or unavailability before using alternatives. Preserve existing project instructions.
+
 ## Workspace files and storage
 
 All file tools use string paths such as `project/src/main.cpp` and
 `storage/build/debug`. Directory tools default to `project/`; the separate tool
 argument `root` has been removed. Python consumers use the shared `WorkspacePath`
-type, which serializes as the same string. Storage defaults to `.<project-name>.forgemcp` beside the
-project. Set its location explicitly when needed:
+type, which serializes as the same string. Tool path arguments also accept ordinary
+relative paths: `src/main.cpp` and `./src/main.cpp` both mean `project/src/main.cpp`,
+and `./` means `project/`. One trailing `/` is accepted for managed paths:
+`project/src/` becomes `project/src`. Results always use canonical qualified paths.
+The prefixes `project/`, `storage/`, and `root/` are reserved; use `./storage/...`
+to access a project directory named `storage`. Absolute paths, `..`, and repeated
+separators remain invalid; external locations require an explicit `root/` prefix.
+
+Storage defaults to `.<project-name>.forgemcp` beside the project. Set its location
+explicitly when needed:
 
 ```powershell
 forgemcp --workspace C:\Projects\Example --workspace-storage D:\ForgeMCP\Example
@@ -192,7 +211,7 @@ a working-directory check, not an operating-system sandbox.
 | `workspace_find_files(pattern="*", path="project/")` | Recursive filename/path glob search |
 | `workspace_file_info(path)` | Creation/modification times, byte size, owner; unavailable metadata is null |
 | `workspace_read_file(path, start_line=1, end_line=null)` | UTF-8 text, with an optional inclusive line range |
-| `workspace_search(query, path="project/", regex=false, extensions=null, case_sensitive=true)` | Matching lines and skipped binary/non-UTF-8 files |
+| `workspace_text_search(query, path="project/", regex=false, extensions=null, case_sensitive=true, max_matches=100)` | Bounded matching lines, exact counts, and a linked skipped-file list |
 | `workspace_write_file(path, text)` | Create or overwrite; return removed/added line counts |
 | `workspace_edit_file(path, old_text, new_text, replace_all=false)` | Exact replacement; zero or ambiguous matches fail without modifying the file |
 | `workspace_move(source, destination)` | Move a file or directory; destination must not exist |
@@ -209,8 +228,15 @@ dot-prefixed files remain visible. Searches skip directories beginning with a do
 access hidden directories and in-root links. Mutations cannot traverse links;
 moving/removing a whole tree containing links is rejected. Dependent modules may
 register protected paths, which remain readable but cannot be changed through the
-workspace API. Searches intentionally have no application-level timeout, result
-limit, or pagination in this iteration.
+workspace API. Searches have no application-level timeout or pagination. Text search
+returns at most `max_matches` matching lines (positive integer, default 100), with
+all spans on each returned line. It continues scanning to return exact
+`matches_count` and `skipped_files_count`; `matches_truncated` indicates omitted
+matching lines. The complete binary/non-UTF-8 file list is an immutable JSON resource
+linked as `resources.skipped_files` when nonempty, rather than inline output.
+The widget loads that snapshot for its skipped-files tab. Narrow the path/extensions
+or increase `max_matches` to retrieve more matching lines. Individual lines and their
+span arrays have no byte limit.
 
 File resource templates use a single path including its project/ or storage/ prefix:
 
@@ -220,7 +246,7 @@ forgemcp://workspace/raw{/path*}
 forgemcp://workspace/list{?path,depth,include_hidden}
 forgemcp://workspace/find-files{?pattern,path}
 forgemcp://workspace/file-info{?path}
-forgemcp://workspace/search{?query,path,regex,extensions,case_sensitive}
+forgemcp://workspace/search{?query,path,regex,extensions,case_sensitive,max_matches}
 forgemcp://workspace/results/{result_id}/{name}.json
 forgemcp://workspace/results/{result_id}/{name}.md
 ```
@@ -254,10 +280,26 @@ A resource-loading failure does not change the successful file-operation outcome
 When a CMake configuration has a compilation database and clangd in its toolset,
 Workspace reads, writes, and edits of C/C++ files also return
 `resources.clangd`. This immutable JSON contains diagnostics and semantic
-highlighting grouped by configuration. Workspace mutations synchronize retained
-clangd sessions; changing a header refreshes already opened dependent files.
+highlighting grouped by configuration, always across all available configurations.
+Clangd analyzes the complete file even for a partial Workspace read, but the saved
+diagnostics and semantic spans include only those intersecting the lines actually
+returned. Their coordinates remain absolute file positions; an empty partial-read
+excerpt (for example, beyond EOF) has no annotations.
+
 Clangd starts sessions from CMake's configuration subscription and keeps them until
 the configuration disappears, its database changes, or the server stops.
+Each process receives `-j=2`; this worker setting does not impose a memory limit.
+File analysis opens the complete current file, collects the requested result, and
+closes the document before returning. Documents are not retained between calls, so
+the next analysis incorporates saved header changes without reopening other files
+after each Workspace mutation. Repeated calls pay the cost of a fresh file parse;
+closing a document does not release clangd's whole index. Workspace mutations still
+notify sessions of filesystem changes and reconcile changed compilation databases.
+Explicit clangd tools use their existing `configurations` argument to select a
+subset, for example
+`clangd_diagnostics(path="project/src/main.cpp", configurations=["debug"])`.
+Omitting that argument or passing `[]` selects all available configurations.
+
 Workspace widgets load both resources independently. The source view lets you
 select a configuration for semantic highlighting and inline diagnostic markers;
 lexical C/C++ colors also cover keywords, comments, literals, directives, and nested

{forge_cpp_mcp-0.2.1 → forge_cpp_mcp-0.2.3}/README.md

@@ -32,8 +32,12 @@ debugger modules are planned.
   toolsets as markdown, querying available versions for details, with completion
   for retained toolset IDs.
 
-The tools remain useful in clients without MCP Apps support because the Python SDK
-serializes their typed results into both text `content` and `structuredContent`.
+Every tool returns readable English plain text in `content` alongside its typed
+`structuredContent`. Trees use branch characters, source excerpts use line numbers,
+and diagnostics use compiler-style messages. Text does not include Markdown
+formatting or Workspace provider resource links; the structured data retains those
+links for widgets. Clients decide how to display the text and may prefer structured
+data when supplying results to a model.
 
 All widgets share a compact console style with a fixed 420px height and adapt to the
 host width. The move confirmation uses only two rows, source and destination.
@@ -64,7 +68,7 @@ and install it in a virtual environment:
 
 ```powershell
 python -m venv .venv
-.\.venv\Scripts\python.exe -m pip install .\forge_cpp_mcp-0.2.1-py3-none-any.whl
+.\.venv\Scripts\python.exe -m pip install .\forge_cpp_mcp-0.2.3-py3-none-any.whl
 .\.venv\Scripts\forgemcp.exe --help
 ```
 
@@ -76,7 +80,7 @@ The distribution name is `forge-cpp-mcp`; the Python module and server command a
 After the package is published to PyPI, the install command can instead be:
 
 ```powershell
-.\.venv\Scripts\python.exe -m pip install forge-cpp-mcp==0.2.1
+.\.venv\Scripts\python.exe -m pip install forge-cpp-mcp==0.2.3
 ```
 
 ## Setup from source
@@ -139,13 +143,27 @@ add the `forgemcp` entry to it rather than replacing the file. Restart the clien
 after editing its configuration. Check the connection with `codex mcp list` or
 `claude mcp get forgemcp`, respectively.
 
+To require agents to use ForgeMCP for supported operations, append the
+[example agent instructions](examples/mcp-clients/agent-instructions.md) to your
+project's `AGENTS.md` (Codex) or `CLAUDE.md` (Claude Code). The same block works
+for both clients and requires evidence of an unsupported operation, tool failure,
+or unavailability before using alternatives. Preserve existing project instructions.
+
 ## Workspace files and storage
 
 All file tools use string paths such as `project/src/main.cpp` and
 `storage/build/debug`. Directory tools default to `project/`; the separate tool
 argument `root` has been removed. Python consumers use the shared `WorkspacePath`
-type, which serializes as the same string. Storage defaults to `.<project-name>.forgemcp` beside the
-project. Set its location explicitly when needed:
+type, which serializes as the same string. Tool path arguments also accept ordinary
+relative paths: `src/main.cpp` and `./src/main.cpp` both mean `project/src/main.cpp`,
+and `./` means `project/`. One trailing `/` is accepted for managed paths:
+`project/src/` becomes `project/src`. Results always use canonical qualified paths.
+The prefixes `project/`, `storage/`, and `root/` are reserved; use `./storage/...`
+to access a project directory named `storage`. Absolute paths, `..`, and repeated
+separators remain invalid; external locations require an explicit `root/` prefix.
+
+Storage defaults to `.<project-name>.forgemcp` beside the project. Set its location
+explicitly when needed:
 
 ```powershell
 forgemcp --workspace C:\Projects\Example --workspace-storage D:\ForgeMCP\Example
@@ -168,7 +186,7 @@ a working-directory check, not an operating-system sandbox.
 | `workspace_find_files(pattern="*", path="project/")` | Recursive filename/path glob search |
 | `workspace_file_info(path)` | Creation/modification times, byte size, owner; unavailable metadata is null |
 | `workspace_read_file(path, start_line=1, end_line=null)` | UTF-8 text, with an optional inclusive line range |
-| `workspace_search(query, path="project/", regex=false, extensions=null, case_sensitive=true)` | Matching lines and skipped binary/non-UTF-8 files |
+| `workspace_text_search(query, path="project/", regex=false, extensions=null, case_sensitive=true, max_matches=100)` | Bounded matching lines, exact counts, and a linked skipped-file list |
 | `workspace_write_file(path, text)` | Create or overwrite; return removed/added line counts |
 | `workspace_edit_file(path, old_text, new_text, replace_all=false)` | Exact replacement; zero or ambiguous matches fail without modifying the file |
 | `workspace_move(source, destination)` | Move a file or directory; destination must not exist |
@@ -185,8 +203,15 @@ dot-prefixed files remain visible. Searches skip directories beginning with a do
 access hidden directories and in-root links. Mutations cannot traverse links;
 moving/removing a whole tree containing links is rejected. Dependent modules may
 register protected paths, which remain readable but cannot be changed through the
-workspace API. Searches intentionally have no application-level timeout, result
-limit, or pagination in this iteration.
+workspace API. Searches have no application-level timeout or pagination. Text search
+returns at most `max_matches` matching lines (positive integer, default 100), with
+all spans on each returned line. It continues scanning to return exact
+`matches_count` and `skipped_files_count`; `matches_truncated` indicates omitted
+matching lines. The complete binary/non-UTF-8 file list is an immutable JSON resource
+linked as `resources.skipped_files` when nonempty, rather than inline output.
+The widget loads that snapshot for its skipped-files tab. Narrow the path/extensions
+or increase `max_matches` to retrieve more matching lines. Individual lines and their
+span arrays have no byte limit.
 
 File resource templates use a single path including its project/ or storage/ prefix:
 
@@ -196,7 +221,7 @@ forgemcp://workspace/raw{/path*}
 forgemcp://workspace/list{?path,depth,include_hidden}
 forgemcp://workspace/find-files{?pattern,path}
 forgemcp://workspace/file-info{?path}
-forgemcp://workspace/search{?query,path,regex,extensions,case_sensitive}
+forgemcp://workspace/search{?query,path,regex,extensions,case_sensitive,max_matches}
 forgemcp://workspace/results/{result_id}/{name}.json
 forgemcp://workspace/results/{result_id}/{name}.md
 ```
@@ -230,10 +255,26 @@ A resource-loading failure does not change the successful file-operation outcome
 When a CMake configuration has a compilation database and clangd in its toolset,
 Workspace reads, writes, and edits of C/C++ files also return
 `resources.clangd`. This immutable JSON contains diagnostics and semantic
-highlighting grouped by configuration. Workspace mutations synchronize retained
-clangd sessions; changing a header refreshes already opened dependent files.
+highlighting grouped by configuration, always across all available configurations.
+Clangd analyzes the complete file even for a partial Workspace read, but the saved
+diagnostics and semantic spans include only those intersecting the lines actually
+returned. Their coordinates remain absolute file positions; an empty partial-read
+excerpt (for example, beyond EOF) has no annotations.
+
 Clangd starts sessions from CMake's configuration subscription and keeps them until
 the configuration disappears, its database changes, or the server stops.
+Each process receives `-j=2`; this worker setting does not impose a memory limit.
+File analysis opens the complete current file, collects the requested result, and
+closes the document before returning. Documents are not retained between calls, so
+the next analysis incorporates saved header changes without reopening other files
+after each Workspace mutation. Repeated calls pay the cost of a fresh file parse;
+closing a document does not release clangd's whole index. Workspace mutations still
+notify sessions of filesystem changes and reconcile changed compilation databases.
+Explicit clangd tools use their existing `configurations` argument to select a
+subset, for example
+`clangd_diagnostics(path="project/src/main.cpp", configurations=["debug"])`.
+Omitting that argument or passing `[]` selects all available configurations.
+
 Workspace widgets load both resources independently. The source view lets you
 select a configuration for semantic highlighting and inline diagnostic markers;
 lexical C/C++ colors also cover keywords, comments, literals, directives, and nested

{forge_cpp_mcp-0.2.1 → forge_cpp_mcp-0.2.3}/frontend/src/shared/app.js

@@ -1,6 +1,6 @@
 import { App, PostMessageTransport, applyDocumentTheme, applyHostFonts, applyHostStyleVariables } from "@modelcontextprotocol/ext-apps";
 import { createResultView } from "./result-view.js";
-import { loadResultClangd, loadResultDiff } from "./result-resources.js";
+import { loadResultClangd, loadResultDiff, loadResultSkippedFiles } from "./result-resources.js";
 import "./widget.css";
 
 /** Lifecycle bridge and immutable result-resource loading; never calls tools. */
@@ -34,6 +34,7 @@ export async function connectWidget({ toolName, describe, renderValue }) {
     if (result?.isError || data?.action === "moved") return;
     await Promise.all([
       ["diff", loadResultDiff], ["clangd", loadResultClangd],
+      ["skipped_files", loadResultSkippedFiles],
     ].filter(([name]) => data?.resources?.[name]).map(async ([name, load]) => {
       try {
         const resource = await load(result, (params) => app.readServerResource(params), () => current === generation);

{forge_cpp_mcp-0.2.1 → forge_cpp_mcp-0.2.3}/frontend/src/shared/result-resources.js

@@ -47,6 +47,20 @@ function resultResourceUri(link, provider) {
   return link.uri;
 }
 
+export async function loadResultSkippedFiles(result, read, current = () => true) {
+  const link = result?.structuredContent?.resources?.skipped_files;
+  if (!link || result.isError) return null;
+  const uri = resultResourceUri(link, "skipped_files");
+  if (!current()) return null;
+  const data = decode(await read({ uri }), uri);
+  if (!Array.isArray(data?.skipped_files) || !data.skipped_files.every((path) =>
+    typeof path === "string" && /^(project|storage)\//.test(path))
+    || data.skipped_files.length !== result.structuredContent.skipped_files_count) {
+    throw new Error("Invalid skipped-file resource");
+  }
+  return current() ? data : null;
+}
+
 export async function loadResultClangd(result, read, current = () => true) {
   const link = result?.structuredContent?.resources?.clangd;
   if (!link || result.isError) return null;

{forge_cpp_mcp-0.2.1 → forge_cpp_mcp-0.2.3}/frontend/src/shared/result-view.js

@@ -272,7 +272,7 @@ export function createResultView(root, { toolName, describe, renderValue }) {
           copyResource.addEventListener("click", () => { void copy(JSON.stringify(resource, null, 2)); });
           heading.append(copyResource);
           content.append(heading, json);
-        } else if (["diff", "clangd"].includes(name)) {
+        } else if (["diff", "clangd", "skipped_files"].includes(name)) {
           content.append(element("p", "fm-empty", `${name}: ${resourceData[`${name}State`] === "error" ? "Resource could not be loaded." : "Loading resource…"}`));
         }
       }

{forge_cpp_mcp-0.2.1 → forge_cpp_mcp-0.2.3}/frontend/src/workspace-search.js

@@ -1,4 +1,4 @@
 import { connectWidget } from "./shared/app.js";
 import { workspacePresentation, workspaceValue } from "./workspace-view.js";
 
-await connectWidget({ toolName: "workspace_search", describe: workspacePresentation, renderValue: workspaceValue });
+await connectWidget({ toolName: "workspace_text_search", describe: workspacePresentation, renderValue: workspaceValue });

{forge_cpp_mcp-0.2.1 → forge_cpp_mcp-0.2.3}/frontend/src/workspace-view.js

@@ -3,7 +3,7 @@ import { isObject } from "./shared/presentation.js";
 import { clangdValue } from "./clangd-view.js";
 import { appendSourceText, cppSyntax, sourceConfiguration } from "./source-view.js";
 
-function searchView(doc, data, query, width) {
+function searchView(doc, data, query, width, loaded) {
   const node = (tag, className, text) => {
     const result = doc.createElement(tag);
     result.className = className;
@@ -17,7 +17,7 @@ function searchView(doc, data, query, width) {
   const matches = node("div", "fm-search-matches");
   const skipped = node("div", "fm-search-skipped");
   const panels = [matches, skipped];
-  const buttons = ["Matches", `Skipped files (${data.skipped_files?.length ?? 0})`].map((title, index) => {
+  const buttons = ["Matches", `Skipped files (${data.skipped_files_count})`].map((title, index) => {
     const button = node("button", "", title);
     button.type = "button";
     button.id = `workspace-search-tab-${index}`;
@@ -127,9 +127,14 @@ function searchView(doc, data, query, width) {
     matches.append(file);
   }
   if (!groups.size) matches.append(node("p", "fm-empty", "No matching lines."));
-  const paths = (data.skipped_files ?? []).filter((path) => path.toLocaleLowerCase().includes(query));
+  const paths = (loaded.skipped_files?.skipped_files ?? []).filter((path) => path.toLocaleLowerCase().includes(query));
   for (const path of paths) skipped.append(node("div", "fm-skipped-path", path));
-  if (!paths.length) skipped.append(node("p", "fm-empty", "No skipped files."));
+  if (!paths.length) skipped.append(node("p", "fm-empty", data.skipped_files_count === 0
+    ? "No skipped files." : loaded.skipped_filesState === "error"
+      ? "Skipped-file resource could not be loaded." : loaded.skipped_filesState === "ready"
+        ? "No skipped files match the filter." : "Loading skipped files…"));
+  if (data.matches_truncated) matches.prepend(node("p", "fm-empty",
+    `Showing ${data.matches.length} of ${data.matches_count} matching lines (matches_truncated=true). Narrow the search or increase max_matches.`));
   view.append(tabs, matches, skipped);
   return view;
 }
@@ -212,10 +217,10 @@ export function workspacePresentation(data, loaded = {}) {
   }
   if (Array.isArray(data.matches)) {
     return {
-      toolName: "workspace_search", summary: data, records: null,
+      toolName: "workspace_text_search", summary: data, records: null,
       resourceFields: resources(data), filterPlaceholder: "Search results",
-      count: `${data.matches.length} matches · ${new Set(data.matches.map((match) => match.path)).size} files`,
-      render: (doc, query, width) => searchView(doc, data, query, width),
+      count: `${data.matches.length}/${data.matches_count} matching lines · ${data.skipped_files_count} skipped files`,
+      render: (doc, query, width) => searchView(doc, data, query, width, loaded),
     };
   }
   const toolName = Array.isArray(data.entries) ? "workspace_list"

{forge_cpp_mcp-0.2.1 → forge_cpp_mcp-0.2.3}/hatch_build.py

@@ -14,6 +14,7 @@ class CustomBuildHook(BuildHookInterface):
     """Produce frontend assets as part of the wheel build."""
 
     def initialize(self, version: str, build_data: dict[str, object]) -> None:
+        """Build missing frontend assets and include them in the wheel artifacts."""
         frontend = Path(self.root) / "frontend"
         outputs = [
             *(

{forge_cpp_mcp-0.2.1 → forge_cpp_mcp-0.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "forge-cpp-mcp"
-version = "0.2.1"
+version = "0.2.3"
 description = "A safe MCP server for structured C++ project development workflows."
 readme = "README.md"
 requires-python = ">=3.13"
@@ -15,6 +15,7 @@ dependencies = [
     "mcp[cli]==2.1.1",
     "pydantic>=2.13",
     "regex>=2024.11.6",
+    "markdown-it-py>=4.0",
 ]
 
 [project.optional-dependencies]

{forge_cpp_mcp-0.2.1 → forge_cpp_mcp-0.2.3}/src/forgemcp/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.2.1"
+__version__ = "0.2.3"

{forge_cpp_mcp-0.2.1 → forge_cpp_mcp-0.2.3}/src/forgemcp/assets.py

@@ -36,10 +36,12 @@ class Widget:
 
     @property
     def uri(self) -> str:
+        """Return the stable UI resource URI derived from the packaged filename."""
         return f"ui://forgemcp/{PurePosixPath(self.path).name}"
 
     @property
     def content(self) -> str:
+        """Read the packaged widget as UTF-8 HTML."""
         return package_file(self.path).read_text(encoding="utf-8")
 
 
@@ -52,6 +54,7 @@ class IconFile:
 
     @property
     def icon(self) -> Icon:
+        """Encode the packaged icon as portable MCP metadata with its MIME type and sizes."""
         resource = package_file(self.path)
         mime_type = mimetypes.guess_type(self.path)[0] or "application/octet-stream"
         encoded = base64.b64encode(resource.read_bytes()).decode("ascii")

{forge_cpp_mcp-0.2.1 → forge_cpp_mcp-0.2.3}/src/forgemcp/clangd/errors.py

@@ -21,6 +21,7 @@ class ClangdRequestError(ClangdError):
     """The language server rejected an operation."""
 
     def __init__(self, method: str, code: int, message: str) -> None:
+        """Retain the server error code and describe the failed LSP method."""
         super().__init__(f"{method} failed ({code}): {message}")
         self.code = code
 

forge_cpp_mcp-0.2.3/src/forgemcp/clangd/models.py

@@ -0,0 +1,186 @@
+"""Language values shared by session decoding and service results."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, Field, model_validator
+
+from forgemcp.workspace.path import WorkspacePath
+
+
+class Position(BaseModel):
+    """A one-based source line and zero-based Unicode character offset."""
+
+    line: int = Field(ge=1)
+    character: int = Field(ge=0, description="Zero-based Unicode code point offset.")
+
+
+class SourceRange(BaseModel):
+    """An ordered pair of source positions delimiting a range."""
+
+    start: Position
+    end: Position
+
+    @model_validator(mode="after")
+    def ordered(self) -> SourceRange:
+        """Reject ranges whose end precedes the start."""
+        if (self.end.line, self.end.character) < (self.start.line, self.start.character):
+            raise ValueError("Source range end precedes its start.")
+        return self
+
+
+class Location(BaseModel):
+    """A qualified file path and source range."""
+
+    path: WorkspacePath
+    range: SourceRange
+
+
+class SourceExcerpt(BaseModel):
+    """Immutable source context captured with a navigation answer."""
+
+    start_line: int = Field(ge=1)
+    text: str
+
+
+class NavigationLocation(Location):
+    """A navigation target with optional saved source context."""
+
+    preview: SourceExcerpt | None = Field(
+        default=None,
+        description="Up to seven saved source lines near the target. External or unreadable files have no preview.",
+    )
+
+
+class RelatedDiagnostic(BaseModel):
+    """A diagnostic note attached to another source location."""
+
+    location: Location
+    message: str
+
+
+class Diagnostic(BaseModel):
+    """A source diagnostic with severity, provenance, tags, and related notes."""
+
+    range: SourceRange
+    severity: Literal["error", "warning", "information", "hint"] | None = None
+    message: str
+    code: int | str | None = None
+    source: str | None = None
+    tags: list[int] = Field(default_factory=list)
+    related: list[RelatedDiagnostic] = Field(default_factory=list)
+
+
+class HoverText(BaseModel):
+    """One hover fragment with its format and optional code language."""
+
+    kind: Literal["plaintext", "markdown", "code"]
+    text: str
+    language: str | None = None
+
+
+class Hover(BaseModel):
+    """Hover fragments and the optional source range they describe."""
+
+    contents: list[HoverText]
+    range: SourceRange | None = None
+
+
+class DocumentSymbol(BaseModel):
+    """A hierarchical symbol with its full range and name selection range."""
+
+    name: str
+    kind: int
+    range: SourceRange
+    selection_range: SourceRange
+    detail: str | None = None
+    tags: list[int] = Field(default_factory=list)
+    children: list[DocumentSymbol] = Field(default_factory=list)
+
+
+class WorkspaceSymbol(BaseModel):
+    """A workspace symbol with a navigation target and optional containing scope."""
+
+    name: str
+    kind: int
+    location: NavigationLocation
+    container_name: str | None = None
+    tags: list[int] = Field(default_factory=list)
+
+
+class HighlightSpan(BaseModel):
+    """A semantic source range with its token kind and modifiers."""
+
+    range: SourceRange
+    kind: str
+    modifiers: list[str] = Field(default_factory=list)
+
+
+class DiagnosticsResult(BaseModel):
+    """Diagnostics for one file with the configurations that produced them."""
+
+    configurations: list[str]
+    path: WorkspacePath
+    diagnostics: list[Diagnostic]
+
+
+class HoverResult(BaseModel):
+    """A hover answer at a source position with configuration provenance."""
+
+    configurations: list[str]
+    path: WorkspacePath
+    position: Position
+    hover: Hover | None
+
+
+class DefinitionResult(BaseModel):
+    """Definition targets shared by the listed configurations."""
+
+    configurations: list[str]
+    locations: list[NavigationLocation]
+
+
+class ReferencesResult(BaseModel):
+    """Reference targets shared by the listed configurations."""
+
+    configurations: list[str]
+    locations: list[NavigationLocation]
+
+
+class DocumentSymbolsResult(BaseModel):
+    """A file's symbol tree with configuration provenance."""
+
+    configurations: list[str]
+    path: WorkspacePath
+    symbols: list[DocumentSymbol]
+
+
+class WorkspaceSymbolsResult(BaseModel):
+    """Matching workspace symbols with configuration provenance."""
+
+    configurations: list[str]
+    symbols: list[WorkspaceSymbol]
+
+
+class HighlightingResult(BaseModel):
+    """Semantic spans for a file with configuration provenance."""
+
+    configurations: list[str]
+    path: WorkspacePath
+    spans: list[HighlightSpan]
+
+
+class FileAnalysis(BaseModel):
+    """Saved diagnostic and highlighting answers for one file."""
+
+    path: WorkspacePath
+    diagnostics: list[DiagnosticsResult]
+    highlighting: list[HighlightingResult]
+
+
+class ClangdResource(BaseModel):
+    """The versioned payload of an immutable workspace analysis resource."""
+
+    version: Literal[1] = 1
+    files: list[FileAnalysis]