james/carol
james/carol
1
1
Fork 0
Code Issues 44 Pull requests 7 Projects Releases 25 Packages 1 Wiki Activity Actions

docs: add the agent / MCP setup guide for self-hosters #360

Merged
james merged 1 commit from agent-setup-guide into main 2026-06-29 13:33:03 +00:00
Conversation 1 Commits 1 Files changed 2 +228 -1
james commented 2026-06-29 13:04:36 +00:00
Owner
Copy link

Carol now ships a built-in chat agent and a streamable-HTTP MCP endpoint, but there was no end-to-end setup doc. Adds docs/agent-setup-guide.md covering both paths.

Contents

  • Enabling the built-in chat — the CAROL_ENCRYPTION_KEY operator step (links to the README Configuration table rather than restating the env-var surface, per CLAUDE.md), per-user provider config (provider/model/baseUrl/apiKey), and a reverse-proxy note so the SSE token stream isn't buffered.
  • Connecting an external agent over MCP — minting a PAT, then Claude Code, opencode, a generic MCP client + a curl smoke test, and the propose-then-confirm write behavior.
  • Troubleshooting table.

README links to the guide from the CAROL_ENCRYPTION_KEY row and the MCP section; no env-var defaults are duplicated (links only). Design references point to ADR-0029/0030/0031.

Verified

  • Cross-checked against source: CAROL_ENCRYPTION_KEY 503 behavior (settings/llm/route.ts), provider DTO (lib/dto/llm.ts), SSE headers (lib/api/sse.ts), the MCP route/methods (lib/mcp/server.ts), PAT minting, and that /api/mcp is not in public-routes.ts.
  • claude mcp add syntax matches the existing README snippet (not invented).
  • Every internal link resolves (3 ADRs, OIDC guide, README anchors). No markdown linter is wired in the repo, so links/anchors were checked manually.

Flagged for your eye

  • opencode config: the opencode.json mcp → remote-server block is provided with an explicit note to confirm against opencode's docs — its schema has shifted across releases. The reliable facts (endpoint URL + bearer header) are anchored; the wrapper keys are opencode's. Worth a glance before merge.
  • Model-id examples (claude-sonnet-4-5, gpt-4o-mini) are illustrative — model is a free-form string with no allowlist.

🤖 Generated with Claude Code

Carol now ships a built-in chat agent and a streamable-HTTP MCP endpoint, but there was no end-to-end setup doc. Adds `docs/agent-setup-guide.md` covering both paths. ## Contents - **Enabling the built-in chat** — the `CAROL_ENCRYPTION_KEY` operator step (links to the README Configuration table rather than restating the env-var surface, per CLAUDE.md), per-user provider config (provider/model/baseUrl/apiKey), and a reverse-proxy note so the SSE token stream isn't buffered. - **Connecting an external agent over MCP** — minting a PAT, then Claude Code, opencode, a generic MCP client + a `curl` smoke test, and the propose-then-confirm write behavior. - Troubleshooting table. README links to the guide from the `CAROL_ENCRYPTION_KEY` row and the MCP section; **no env-var defaults are duplicated** (links only). Design references point to ADR-0029/0030/0031. ## Verified - Cross-checked against source: `CAROL_ENCRYPTION_KEY` 503 behavior (`settings/llm/route.ts`), provider DTO (`lib/dto/llm.ts`), SSE headers (`lib/api/sse.ts`), the MCP route/methods (`lib/mcp/server.ts`), PAT minting, and that `/api/mcp` is not in `public-routes.ts`. - `claude mcp add` syntax matches the existing README snippet (not invented). - Every internal link resolves (3 ADRs, OIDC guide, README anchors). No markdown linter is wired in the repo, so links/anchors were checked manually. ## Flagged for your eye - **opencode config**: the `opencode.json` `mcp` → remote-server block is provided with an explicit note to confirm against opencode's docs — its schema has shifted across releases. The reliable facts (endpoint URL + bearer header) are anchored; the wrapper keys are opencode's. Worth a glance before merge. - Model-id examples (`claude-sonnet-4-5`, `gpt-4o-mini`) are illustrative — model is a free-form string with no allowlist. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
docs: add the agent / MCP setup guide for self-hosters
All checks were successful
PR / Trivy (image) (pull_request) Successful in 2m15s
Details
PR / Test (sqlite) (pull_request) Successful in 3m35s
Details
PR / Test (postgres) (pull_request) Successful in 3m43s
Details
PR / Coverage (soft) (pull_request) Successful in 2m55s
Details
PR / E2E (Playwright) (pull_request) Successful in 4m16s
Details
Commits / Conventional Commits (pull_request) Successful in 27s
Details
PR / Lint (pull_request) Successful in 2m34s
Details
PR / OpenAPI (pull_request) Successful in 2m16s
Details
PR / Typecheck (pull_request) Successful in 2m43s
Details
PR / Static analysis (pull_request) Successful in 2m35s
Details
PR / Client (web export smoke) (pull_request) Successful in 2m26s
Details
PR / Build (pull_request) Successful in 3m18s
Details
PR / pnpm audit (pull_request) Successful in 2m14s
Details
PR / OSV-Scanner (pull_request) Successful in 2m5s
Details
PR / Package age policy (soft) (pull_request) Successful in 1m28s
Details
Secrets / gitleaks (pull_request) Successful in 33s
Details
eceea52607
 
Carol now ships a built-in chat agent and a streamable-HTTP MCP endpoint,
but there was no end-to-end setup doc. Add docs/agent-setup-guide.md
covering both paths:

- Enabling the built-in chat: the CAROL_ENCRYPTION_KEY operator step
  (links to the README Configuration table rather than restating the
  env-var surface), per-user provider config, and a reverse-proxy note
  so the SSE token stream isn't buffered.
- Connecting an external agent over MCP: minting a PAT, then Claude Code,
  opencode (with a note to confirm opencode's evolving config schema),
  and a generic MCP client + a curl smoke test. Writes are
  propose-then-confirm.

README links to the guide from the CAROL_ENCRYPTION_KEY row and the MCP
section; no env-var defaults are duplicated. Design lives in
ADR-0029/0030/0031.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
forgejo-actions commented 2026-06-29 13:17:49 +00:00
Copy link

📊 Test coverage

Patch coverage: no testable lines changed.

Overall (app/, lib/, db/, excluding UI per ADR-0019):

Metric Value Soft target
Lines 79.3% ✅ ≥ 50%
Branches 71.1% ⚠️ ≥ 75%
Functions 80.5% informational

Soft thresholds per ADR-0019. Coverage is informational and does not block merge.

<!-- coverage-comment --> ## 📊 Test coverage **Patch coverage:** no testable lines changed. **Overall** (`app/`, `lib/`, `db/`, excluding UI per ADR-0019): | Metric | Value | Soft target | |---|---|---| | Lines | 79.3% ✅ | ≥ 50% | | Branches | 71.1% ⚠️ | ≥ 75% | | Functions | 80.5% | informational | Soft thresholds per [ADR-0019](docs/adr/0019-coverage-soft-targets.md). Coverage is informational and does not block merge.
james merged commit 9e8c34dece into main 2026-06-29 13:33:03 +00:00
james deleted branch agent-setup-guide 2026-06-29 13:33:04 +00:00
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels   
area:auth
Authentication and authorization

  
area:ci
Forgejo Actions, build, test, security, release

  
area:db
Database abstraction, migrations, persistence

  
area:infra
Containerization, deployment, foundational tooling

  
area:native
React Native app (Android + Linux Flatpak)

  
area:pwa
PWA / web frontend

  
area:service
Backend service, API routes, persistence

  
epic
High-level tracker; links several feature tickets

  
feature
A user-facing feature

  
foundation
Foundational work that other tickets build on

No labels
area:auth
area:ci
area:db
area:infra
area:native
area:pwa
area:service
epic
feature
foundation
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
2 participants
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
james/carol!360
No description provided.