Skip to content

Self-hosted project management for devs and their clients: tickets, time tracking, docs and meetings, with an AI assistant that cites its sources. AGPL-3.0.

docs(mcp): describe list_organisations and list_projects

Guido Boyke302d7c6ee259
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 26603cc..075a2ce 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -25,6 +25,9 @@ starts (`db:prepare lalabase:data_backfills`). Without Docker, run
signed record of where it was built (`gh attestation verify oci://ghcr.io/lalabase/lalabase:<version> --owner lalabase`).
`compose.yml` of a release pulls the image of that release instead of building it, and
`compose.build.yml` still builds the image from the checkout (#48).
+- The MCP tools `list_organisations` and `list_projects`: an agent now finds the ids the other
+ tools ask for itself, instead of taking them from the address bar. `GET /api/v1/organisations`
+ and `GET /api/v1/projects` read through the same code and answer as before.
### Fixed
diff --git a/CLAUDE.md b/CLAUDE.md
index af61a57..b8d67e5 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -875,6 +875,14 @@ reach, organisations AND projects, and only the rows the web time list shows the
its minutes, with `ticket: null`. Owner: `TimeSessions::OpenHours`; guard:
`spec/requests/api/v1/time_sessions_open_access_spec.rb`.
+`GET /api/v1/organisations` and `GET /api/v1/projects` read through
+`PersonalAccessTokens::ReachListing`, the reader of the MCP tools `list_organisations` and
+`list_projects` (MCP 0.15.0). The rows are the same, the rest differs on purpose: REST answers 200
+with `[]` for an organisation out of reach and shows an admin archived projects unpaged and uncut;
+MCP answers `not_found`, shows archived projects on request, pages by 100 and cuts a description.
+Guards: `spec/services/personal_access_tokens/reach_listing_spec.rb`,
+`spec/requests/api/mcp_list_projects_spec.rb` (every listed id passes the project gate).
+
`GET /api/v1/projects/:project_id/knowledge` (REST R2, 2026-10-29, API 1.6.0, capability
`knowledge.search`) lists a project's notes and documents by title through `Knowledge::Lookup`,
the read the MCP tool `search_knowledge` uses: the same rows, order (`updated_at` newest first,
diff --git a/app/services/CLAUDE.md b/app/services/CLAUDE.md
index ce18f38..7e96dcb 100644
--- a/app/services/CLAUDE.md
+++ b/app/services/CLAUDE.md
@@ -1,4 +1,4 @@
-# Karte: app/services (Stand: 2026-10-30)
+# Karte: app/services (Stand: 2026-10-31)
**Entry-Point-Konvention für NEUE Services: `Klass.call(**kwargs)`** (Klassenmethode; eine
Instanz-`#call`-Implementierung dahinter ist erlaubt). Pflicht: mindestens 1 Kommentarzeile
@@ -223,6 +223,12 @@ Verzeichnis-Übersicht (Auswahl):
without `format` stays byte for byte). Not a second rule: do not align them in one hull.
Encodings: JSON and forms always give UTF-8; a multipart part may name its own charset,
which an html body keeps (ActionText reads it, as before) and a plain body transcodes.
+* `personal_access_tokens/` — `reach_listing.rb` (31.10.2026) is the ONE read of a token's
+ organisations and projects as rows, for `GET /api/v1/organisations`, `GET /api/v1/projects` and
+ the MCP tools `list_organisations` and `list_projects`. Reach (`PersonalAccessToken::Reach`) AND
+ the policy scope decide. It asks `Pundit.policy_scope!` per organisation, never the controller
+ helper, which memoises per scope object. The method `projects_in_organisation` keeps its name:
+ `spec/support/prosopite.rb` allow-lists it by that name.
* `lalabase/` — AI/RAG-Domäne (eigene Karte im Ordner)
* `access_check/` — Projekt-Zugriffslogik, 5 Objekte mit überlappenden Prädikaten —
**vor Neubau erst hier prüfen**. `project_access_service.rb` ist der EINE Besitzer der
diff --git a/app/services/lalabase/CLAUDE.md b/app/services/lalabase/CLAUDE.md
index e9fec91..8bda691 100644
--- a/app/services/lalabase/CLAUDE.md
+++ b/app/services/lalabase/CLAUDE.md
@@ -1,4 +1,4 @@
-# Karte: app/services/lalabase (Stand: 2026-10-30)
+# Karte: app/services/lalabase (Stand: 2026-10-31)
AI/RAG-Domäne (Produktname „Lalabase"): alles rund um LLM-Aufrufe, Embeddings und
Codebase-Verständnis.
@@ -107,6 +107,16 @@ Codebase-Verständnis.
`search_knowledge` liest über `Knowledge::Lookup` (`app/services/knowledge/lookup.rb`,
REST R2), denselben Service wie `GET /api/v1/projects/:project_id/knowledge`. Im Werkzeug
bleiben `q` als Pflicht, die nachsichtigen Seiten-Optionen und die Zitationen.
+ `list_organisations` and `list_projects` (MCP 0.15.0, `:mcp` only, the last two tools) name
+ the ids the other tools take. `scope_mode :token`, reads for a read-only token as well. Both
+ read through `PersonalAccessTokens::ReachListing`, the reader of `GET /api/v1/organisations`
+ and `/projects`, so a new rule of the reach belongs there. `list_projects` keeps what is the
+ tool's: archived projects only with `include_archived`, `not_found` for an organisation out
+ of reach (REST answers 200 with `[]`), `per_page` of at most 100 clamped, a description cut
+ after 500 characters. Not `ProjectPolicy#index?`: it refuses an active member without a
+ project, who gets an empty list, so `Base.scoped_by_policy!` marks the decision of the policy
+ scope. Every listed id passes the gate of `Mcp::ToolCall`; the walk is
+ `spec/requests/api/mcp_list_projects_spec.rb`.
Fehler eines Werkzeugs tragen eine Klasse: `Result.invalid_input(msg)` oder
`Result.refused(msg, reason:)`; ohne Code gilt `refused`, auch für ein abgelehntes Speichern
(Modellvalidierung, Actor-Fehler): das beweist keine falsche Eingabe. Spec je Fehlerstelle: