Appearance
MCP Tools Reference
This is the complete 25-tool contract exposed by the official ForeverLM remote connector used by ChatGPT, Claude, Gemini, and Grok. See Connect an AI Assistant for setup.
The native app contains additional device-internal tools for ingestion, connectors, local files, and app automation. Those are not part of the official remote connector and are intentionally omitted here. A connector you build yourself uses that separate device-hosted integration surface.
Status and sources
| Tool | Parameters | Description |
|---|---|---|
get_mcp_status | none | Report connection mode and capabilities. Call this first. |
list_sources | none | List source metadata from the library. |
get_source_content | source_id | Return canonical readable text for one exact source ID. |
search_sources_semantic | query, limit?, threshold?, project_id?, exclude_project_id? | Search on-device source embeddings. This requires an active Mac; hosted MCP reports the capability as unavailable instead of silently changing the result. |
Projects
Projects are explicit scopes. The connector never infers a Project from the app's current selection. A Project's scope includes its own sources plus the sources of Projects it directly lists under Uses context from; responses identify the context Project rather than presenting those sources as copied membership.
| Tool | Parameters | Description |
|---|---|---|
list_projects | include_completed? | List Projects and their source counts. |
get_project | project_id | Return one Project's instructions, research questions, notes, open gaps, and source IDs. |
list_project_sources | project_id | List approved sources and understanding state for one Project. |
get_project_context | project_id, max_source_chars?, include_emergent_state?, include_source_content? | Return Project metadata, linked sources, open gaps, artifact metadata, review state, and optional source excerpts. Project workspace-file bodies and artifact Markdown live in iCloud Drive and are unavailable to the always-on hosted service; the response reports that limitation explicitly. |
Schedule and Learning Journey
Read the current Schedule before proposing or changing a plan. Dates use YYYY-MM-DD in the learner's local calendar.
| Tool | Parameters | Description |
|---|---|---|
get_learning_journey | goal_id?, include_completed? | Return the current Schedule week, placements, completion state, and goal tags. |
get_today_sources | goal_id?, date?, date_basis?, activity_kind?, include_completed?, max_chars_per_source? | Return readable content for sources planned, used, or completed on a chosen day. |
create_learning_journey | title?, source_ids?, start_date?, end_date? | Create a Schedule goal and optionally place existing sources. |
add_learning_journey_sources | source_ids, goal_id?, date? | Add existing sources and optionally assign a date. |
assign_learning_journey_sources_to_day | source_ids, date, goal_id? | Assign or move sources to a calendar day. goal_id is required when placing a source not already on the Schedule. |
remove_learning_journey_sources | source_ids, goal_id? | Remove sources from a Schedule goal. |
clear_learning_journey_day | date, goal_id?, include_completed? | Remove matching placements from one day. |
mark_learning_journey_day_done | date, goal_id? | Mark every pending source on one day complete. |
set_learning_journey_source_completion | source_id, is_completed, goal_id? | Complete or reopen one scheduled source. |
update_learning_journey | goal_id, title?, start_date?, end_date? | Update the title or date range. The merged final range is validated even when only one boundary changes. |
delete_learning_journey | goal_id? | Delete a Schedule goal and detach its placements. |
Adding material to the library
Ingestion runs through the ForeverLM app's own importer, so a source has exactly one path into the library and its identity, deduplication, and derived data stay consistent. That means these two tools need the learner's Mac to be open and connected; called without one, they answer with an explanation rather than failing silently or filing an empty source.
| Tool | Parameters | Description |
|---|---|---|
add_source | url, title, source_type, content?, author?, parent_group? | File a non-paper source, with its full text when you have already read it. Repeated calls with the same URL deduplicate. |
add_slack_thread | permalink, workspace, channel, messages | Save a Slack thread as a source, deduplicated by the thread permalink. |
Slack
ForeverLM reads Slack as the learner, through a token they granted, and never posts, replies, or reacts. Only channels the learner has explicitly enabled are visible; the rest of the workspace is not.
These two tools are answered by the gateway rather than by a Mac or a hosted account, because the gateway is the only place that holds the workspace credential. Nothing is stored: a channel is read when asked, returned, and forgotten.
| Tool | Parameters | Description |
|---|---|---|
list_slack_channels | — | The channels the learner has enabled, with their names. |
read_slack_channel | channel_id, since_days? | Recent discussion from one enabled channel, with thread replies and posted links. Defaults to 7 days, maximum 90. |
Scheduled tasks
A scheduled task is a recurring instruction ForeverLM sends to itself. The instruction is ordinary chat text: when the task comes due, a signed-in client opens a new chat with this same tool surface and sends it, so the result is a conversation the learner reads and continues.
A run cannot see the conversation that created it, so the instruction must stand alone — carry project_id and source_ids rather than writing "this". Creating a task does not run it, and nothing here executes one: runs happen on a client that is open when the task comes due.
| Tool | Parameters | Description |
|---|---|---|
create_scheduled_task | title, instruction, cadence?, hour?, minute?, weekday?, day_of_month?, date?, time_zone?, project_id?, source_ids?, enabled? | Create a recurring task whose instruction is sent as a chat when it comes due. Wall-clock times are anchored to the task's own IANA zone. |
Review sessions
A completed MCP review keeps the actual exported transcript, not just summary metadata. Source links and Schedule completion are updated only after the review is durably recorded.
| Tool | Parameters | Description |
|---|---|---|
start_review_session | topic, source_id?, source_ids?, project_id?, operation_id? | Create a durable source-grounded Feynman review session. |
end_review_session | session_id, overall_score, summary, transcript?, chat_export?, source_ids?, topic?, gaps?, memory_attempts? | Complete the review, save its transcript, and link Schedule state. The always-on host requires a transcript because it does not own an in-app chat; structured Memory Review evidence requires an active Mac. |
get_review_sessions | topic?, source_id? | List saved reviews, optionally filtered by topic or source. |
get_review_session_transcript | session_id | Return the stored transcript and parsed exchanges. |
import_review_chat | title, transcript, source_ids?, summary?, overall_score?, model_provider?, model_id? | Import an externally completed review as searchable per-turn exchanges and link its completed state. The hosted service requires explicit source_ids; only an active Mac can use its current app selection. |
search_review_sessions | query, limit? | Search saved review topics, summaries, and transcript text. |
Hosted and active-Mac execution
The official connector has one stable list and public input contract regardless of execution mode. Most calls can run from the always-on hosted CloudKit projection. The semantic index, iCloud Drive workspace-file bodies, structured Memory Review completion, and ambient app selection remain device-local. Calls that need those capabilities route to an active Mac when available; otherwise get_mcp_status and the affected response state the limitation directly. Enabling hosted MCP never removes a tool or silently substitutes a different result.