morluto/rea

Fork 0

mirror of https://github.com/morluto/rea.git synced 2026-11-05 07:47:29 +00:00

[PR #4878] docs(clients): document llama.cpp MCP setup #6454

New issue

Open

opened 2026-10-31 01:14:34 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-31 01:14:34 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/4878
Author: @panditshivam
Created: 10/17/2026
Status: 🔄 Open

Base: main ← Head: docs/llama-cpp-setup

📝 Commits (3)

3e59790 docs(clients): document llama.cpp MCP setup
76ecb65 docs(clients): clarify persistent installs and llama.cpp deadlines
bd5121b docs(clients): escape Windows paths in llama.cpp config

📊 Changes

3 files changed (+127 additions, -0 deletions)

View changed files

📝 docs/client-configuration.md (+97 -0)
📝 docs/client-verification.md (+24 -0)
📝 docs/installation.md (+6 -0)

📄 Description

Summary

Fixes #4867. Shows how to connect an installed REA package to llama-server through its native stdio MCP support.

Problem and expected behavior

The client guide has no llama.cpp setup instructions. Users should be able to register REA, choose a local model, and distinguish a connection problem from a model that does not call tools correctly.

Change and scope

Add project-local and optional global install steps, JSON registration, server command, provider-aware timeout guidance, tool selection, and troubleshooting. Link it from installation and record the actual verification limits. This documents the existing MCP interface; a new analysis provider or runtime change is not needed.

Contract and boundary impact

Owner: client configuration, installation, and client verification documentation.
Scope decision: ordinary documentation within the existing MCP boundary; no advance provider decision applies.
CLI, MCP contracts, provider compatibility, and Evidence formats: unchanged.
Example authority: starts llama-server and its REA child with the caller's permissions, bound to loopback. It does not enable llama.cpp's built-in tools or browser MCP proxy. Existing REA operations still need appropriate targets and authorization.
Package, generated metadata, and automatic installer behavior: unchanged. llama.cpp registration is explicitly manual.

Expected effects:

Documentation or usability only; no target interaction.

Evidence and regression coverage

Executed on macOS arm64 with Node 24.18.0 and llama-server b11715 (9d1878a43):

Published rea-agents@6.5.0: GET /tools exposed all 207 REA tools, with no llama.cpp built-in tools enabled.
Source at 9e372c6: all 207 names, descriptions, and input schemas matched a direct MCP client.
POST /tools: session metadata, JavaScript Evidence for a Unicode fixture path, expected missing-target error, and a successful session request after that error. The valid fixture produced four graph nodes.
A Qwen3-1.7B Q8_0 run selected the analysis tool and received its Evidence. Its follow-up reached the output limit; other small-model attempts emitted JSON text instead of tool calls. A full-catalog request exceeded a 16,384-token context. The guide explains these limits rather than claiming reliable model behavior.
The JSON example parses and the three changed pages render with their linked section anchors.

Existing onboarding consistency checks ran. HTTP and stdio were exercised; browser interaction, Windows, and native analysis engines were not.

Validation performed

npm run build:cached — passed.
npm run check — passed, including architecture guards.
npm run docs:check — passed, including all five README consistency tests.
npm run verify:package — passed, including setup/uninstall, skill installation, 207 MCP tools, Evidence, and cleanup checks.
npm pack --dry-run --json — passed.
npm run docs:build — blocked by three existing links in docs/verification/. The same three failures reproduce with the unchanged base documentation at 9e372c6; no link check was disabled. The affected pages are electron-cancellation-2026-10-16.md, javascript-retained-facts-2026-10-15.md, and javascript-window-options-2026-10-16.md.

Review follow-up

Clarified persistent local/global installs and set the example deadline to 450,000 ms, matching the documented default provider allowance plus operation time.
Fresh isolated installs of published REA 6.5.0 both exposed all 207 tools through llama-server b11715 and returned JavaScript Evidence, the expected missing-target error, and a healthy call after that error. Both server processes exited successfully. Optional Frida was omitted; native engines were not exercised.
Reran npm run check and npm run docs:check (five tests). Parsed the JSON, checked both installed entrypoint paths, and rendered the updated guide and its two linked sections.
Windows path follow-up: reproduced invalid JSON and silent escape corruption locally; parsed the guide's forward-slash/doubled-backslash examples, checked both path fields and rendered escaping, and executed the exact JSON-quoted executable command through zsh and bash. Reran npm run check and npm run docs:check (five tests). These checks ran on macOS; Windows execution remains untested.

Compatibility, safety, and release

No breaking change, migration, or package metadata change. Builds without --mcp-servers-config cannot use this route. Successful tool discovery does not show that every model can fit the catalog or use its tools reliably. The documentation records the tested versions and preserves those limits.

Author readiness

Human owner: @panditshivam

I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work.
I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps.
I declare this PR ready for initial maintainer review.

Before merge

Concrete issue linked and focused conventional title used.
Documentation, examples, and validation limits recorded.
Required checks pass for the current revision.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/4878 **Author:** [@panditshivam](https://github.com/panditshivam) **Created:** 10/17/2026 **Status:** 🔄 Open **Base:** `main` ← **Head:** `docs/llama-cpp-setup` --- ### 📝 Commits (3) - [`3e59790`](https://github.com/morluto/rea/commit/3e597903d2d14b473a178d94fc0127c35b25ff42) docs(clients): document llama.cpp MCP setup - [`76ecb65`](https://github.com/morluto/rea/commit/76ecb658451337d9023790d8445c73ea56d97859) docs(clients): clarify persistent installs and llama.cpp deadlines - [`bd5121b`](https://github.com/morluto/rea/commit/bd5121b59299066c252cdfd4074a961b845beba7) docs(clients): escape Windows paths in llama.cpp config ### 📊 Changes **3 files changed** (+127 additions, -0 deletions) <details> <summary>View changed files</summary> 📝 `docs/client-configuration.md` (+97 -0) 📝 `docs/client-verification.md` (+24 -0) 📝 `docs/installation.md` (+6 -0) </details> ### 📄 Description ## Summary Fixes #4867. Shows how to connect an installed REA package to llama-server through its native stdio MCP support. ## Problem and expected behavior The client guide has no llama.cpp setup instructions. Users should be able to register REA, choose a local model, and distinguish a connection problem from a model that does not call tools correctly. ## Change and scope Add project-local and optional global install steps, JSON registration, server command, provider-aware timeout guidance, tool selection, and troubleshooting. Link it from installation and record the actual verification limits. This documents the existing MCP interface; a new analysis provider or runtime change is not needed. ## Contract and boundary impact - Owner: client configuration, installation, and client verification documentation. - Scope decision: ordinary documentation within the existing MCP boundary; no advance provider decision applies. - CLI, MCP contracts, provider compatibility, and Evidence formats: unchanged. - Example authority: starts llama-server and its REA child with the caller's permissions, bound to loopback. It does not enable llama.cpp's built-in tools or browser MCP proxy. Existing REA operations still need appropriate targets and authorization. - Package, generated metadata, and automatic installer behavior: unchanged. llama.cpp registration is explicitly manual. Expected effects: - [x] Documentation or usability only; no target interaction. ## Evidence and regression coverage Executed on macOS arm64 with Node 24.18.0 and llama-server b11715 (`9d1878a43`): - Published `rea-agents@6.5.0`: `GET /tools` exposed all 207 REA tools, with no llama.cpp built-in tools enabled. - Source at `9e372c6`: all 207 names, descriptions, and input schemas matched a direct MCP client. - `POST /tools`: session metadata, JavaScript Evidence for a Unicode fixture path, expected missing-target error, and a successful session request after that error. The valid fixture produced four graph nodes. - A Qwen3-1.7B Q8_0 run selected the analysis tool and received its Evidence. Its follow-up reached the output limit; other small-model attempts emitted JSON text instead of tool calls. A full-catalog request exceeded a 16,384-token context. The guide explains these limits rather than claiming reliable model behavior. - The JSON example parses and the three changed pages render with their linked section anchors. Existing onboarding consistency checks ran. HTTP and stdio were exercised; browser interaction, Windows, and native analysis engines were not. ## Validation performed - `npm run build:cached` — passed. - `npm run check` — passed, including architecture guards. - `npm run docs:check` — passed, including all five README consistency tests. - `npm run verify:package` — passed, including setup/uninstall, skill installation, 207 MCP tools, Evidence, and cleanup checks. - `npm pack --dry-run --json` — passed. - `npm run docs:build` — blocked by three existing links in `docs/verification/`. The same three failures reproduce with the unchanged base documentation at `9e372c6`; no link check was disabled. The affected pages are `electron-cancellation-2026-10-16.md`, `javascript-retained-facts-2026-10-15.md`, and `javascript-window-options-2026-10-16.md`. ### Review follow-up - Clarified persistent local/global installs and set the example deadline to 450,000 ms, matching the documented default provider allowance plus operation time. - Fresh isolated installs of published REA 6.5.0 both exposed all 207 tools through llama-server b11715 and returned JavaScript Evidence, the expected missing-target error, and a healthy call after that error. Both server processes exited successfully. Optional Frida was omitted; native engines were not exercised. - Reran `npm run check` and `npm run docs:check` (five tests). Parsed the JSON, checked both installed entrypoint paths, and rendered the updated guide and its two linked sections. - Windows path follow-up: reproduced invalid JSON and silent escape corruption locally; parsed the guide's forward-slash/doubled-backslash examples, checked both path fields and rendered escaping, and executed the exact JSON-quoted executable command through zsh and bash. Reran `npm run check` and `npm run docs:check` (five tests). These checks ran on macOS; Windows execution remains untested. ## Compatibility, safety, and release No breaking change, migration, or package metadata change. Builds without `--mcp-servers-config` cannot use this route. Successful tool discovery does not show that every model can fit the catalog or use its tools reliably. The documentation records the tested versions and preserves those limits. ## Author readiness Human owner: @panditshivam - [x] I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work. - [x] I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps. - [x] I declare this PR ready for initial maintainer review. ## Before merge - [x] Concrete issue linked and focused conventional title used. - [x] Documentation, examples, and validation limits recorded. - [x] Required checks pass for the current revision. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi added the

pull-request

label

2026-10-31 01:14:34 +00:00

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

morluto/rea#6454

No description provided.

Rows
Columns