MorgenMCP
CLAUDE.md3 starsChanged 4 months agoApache-2.0View on GitHub
The import above pulls in AGENTS.md — the harness-agnostic contributor guide (environment setup, base lint/format/typecheck/test commands, code conventions, scope and safety rules) shared with any other coding-agent tool working in this repo. Edit that file, not this section, when those base commands or conventions change; the two must not drift. Commands specific to working in this repo through Claude Code — beyond the base set in AGENTS.md: Opens Inspector UI at http://localhost:6274 for testing tools. FastMCP-based MCP server wrapping the…
- Reads credentials
- Commits and pushes
The file
We split this CLAUDE.md into the rules it gives an agent
8 rules. About 0 are common, 3 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 65
Bounded batch concurrency: every batch/fan-out asyncio.gather goes through gather_bounded (tools/utils.py, semaphore, BATCH_CONCURRENCY = …
- Distinctive: line 106
Graceful degradation: If the store fails to initialize, the server continues with in-memory-only IDs (session-scoped)
- Very specific: line 120
MORGENMCP_TASKS_LIMIT: Default limit sent to /tasks/list when a caller does not pass one. - Very specific: line 121
MORGENMCP_TAGS_LIMIT: Default limit sent to /tags/list. - Very specific: line 162
When spawning Explore agents, always include this instruction in the prompt: _"For Morgen API questions, search …
- Distinctive: line 185
Treat "no matches" as "check git submodule status first", not as "the docs don't cover it" — otherwise every rule in this section quietly …
- Very specific: line 199
Before implementing or modifying any tool: Search docs/morgen-dev-docs/content/*.mdx directly (grep for the endpoint or resource name, read …
- Distinctive: line 202
When adding a new tool or changing tool signatures: Check both FastMCP local docs (for decorator/return-type patterns) and the MCP protocol …
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
@AGENTS.md
The import above pulls in AGENTS.md — the harness-agnostic contributor guide (environment setup, base lint/format/typecheck/test commands, code conventions, scope and safety rules) shared with any other coding-agent tool working in this repo. Edit that file, not this section, when those base commands or conventions change; the two must not drift.
Quick Reference (Claude Code additions)
Commands specific to working in this repo through Claude Code — beyond the base set in AGENTS.md:
echo 'MORGEN_API_KEY=...' > .env && export UV_ENV_FILE=.env # Configure API key (uv only)
mise trust && mise set --file mise.local.toml MORGEN_API_KEY=... # Same, if you use mise
uv run morgenmcp # Run server
uv run morgenmcp --read-only # Run server with only the read tools (also: MORGENMCP_READ_ONLY=1)
uv run morgenmcp --tasks-limit 25 # Cap /tasks/list results (also: MORGENMCP_TASKS_LIMIT=25)
uv run pytest tests/test_tools.py::TestCreateEvent -v # Run specific test class
uv run pytest tests/test_tools.py::TestCreateEvent::test_create_basic_event -v # Run single test
uv run pytest tests/test_integration.py -v -s -m integration # Run live API testsLocal Debugging
npx @modelcontextprotocol/inspector uv run morgenmcpOpens Inspector UI at http://localhost:6274 for testing tools.
Architecture
FastMCP-based MCP server wrapping the Morgen calendar API (https://api.morgen.so/v3/).
server.py- Entry point registering tools and resources. Tools and resources are not decorated on the function; instead,server.pyusesmcp.tool(name=..., ...)(func)andmcp.resource(uri, ...)(func)as call expressions. This decoupling means tool/resource functions remain plain async functions importable for unit testing.client.py- Async HTTP client; global instance viaget_client(). Auth header:"Authorization": f"ApiKey {self.api_key}"(notBearer).models.py- Pydantic models usingAnnotated[type, Field(alias="...")]pattern. BaseMorgenModelconfig:validate_by_name=True, validate_by_alias=True. Serialize withmodel.model_dump(by_alias=True, exclude_none=True).validators.py- Input validation (datetime, duration, timezone, email, color)resources.py- MCP resource handlers under themorgen://URI scheme. Read-only — writes still go through tools. Static URIs (morgen://server,morgen://accounts,morgen://calendars,morgen://events/today,morgen://events/this-week,morgen://events/upcoming,morgen://tasks,morgen://tasks/today,morgen://tags) and templates (morgen://account/{account_id},morgen://calendar/{calendar_id},morgen://calendar/{calendar_id}/events). All returnapplication/jsonstrings; IDs are virtual, identical to tool output. Renaming any URI is a breaking contract change for saved client chats.tools/- Tool implementations:accounts.py,calendars.py,events.py,tasks.py,tags.py- MCP tool functionsid_registry.py- Virtual ID ↔ real ID bidirectional mapping with disk persistenceid_utils.py- Extract account/calendar IDs from encoded Morgen IDs (events/calendars only — task and tag IDs are opaque)utils.py- Shared helpers (filter_none_values,handle_tool_errors,build_alerts_dict,build_recurrence_rules)
Patterns
- Response caching:
server.pyregisters aResponseCachingMiddlewarewith a 60s in-memory TTL. It caches an explicit allowlist of read-only tools (morgen_list_*,morgen_get_tagviacall_tool;morgen_get_taskis excluded so post-mutation/deletion verification reads are never stale) and all resource reads (read_resource). Writes are intentionally not cached — adding any write tool to_CACHEABLE_READ_TOOLSwould silently turn duplicate creates into no-ops. Storage is in-memory (resets on server restart) — disk persistence would let staleevents/todaysurvive restarts. Cache keys are method+args only (no session identity), which is fine for single-user stdio.- Listing caches are explicitly disabled (
list_tools_settings/list_resources_settings/list_prompts_settingsset to{"enabled": False}). The middleware cachestools/list/resources/list/prompts/listby default with a 5-minute TTL if you passNone; but listing is a pure in-memory component enumeration (no API call), so the cache saves nothing and only risks serving a stale set. Critically, read-only mode toggles tool visibility, and a cachedtools/listwould mask that for up to 5 minutes. Do not re-enable listing caches. - Test isolation: because the cache is a module-level singleton on
mcpkeyed on method+args (no session partition), two tests that call the same cacheable read tool with the same args collide across the 60s TTL. Tests either use disjoint keys (TestResponseCaching) or evict via the publickeys()+delete()API in theisolated_response_cachefixture. Never call_backend.destroy()— it tears down collection-setup state and breaks every subsequentputin the process.
- Listing caches are explicitly disabled (
- Tools return
{"success": True, ...}on success - Tools raise
ToolError(fromfastmcp.exceptions) on failure — messages are always visible to LLMs @handle_tool_errorsinutils.pyconverts ValidationError, MorgenAPIError, and unexpected exceptions to ToolError- Batch operations return partial results with
{"deleted": [...], "failed": [...]}— per-item failures are dict entries, not ToolError - Typed output schemas: Every tool declares a
TypedDictreturn fromtools/outputs.py(notmodels.py— those are alias-based wire models with a different shape than the hand-built camelCase output dicts likecalendarId/isAllDay). This gives each tool a shapedoutputSchemaand makes FastMCP validate every return against it at runtime — a payload missing a schema-requiredfield raisesToolError: Output validation error: '<field>' is a required property. Because tool payloads run throughfilter_none_values(drops None/empty keys), any field that can be absent MUST beNotRequired, or a normal sparse response (account with nodisplayName, event with nodescription) fails. Nested "always-present-but-nullable" values (e.g.update_calendar_metadata'supdated.overrideColor) are typedT | None(key required, value nullable), notNotRequired. The_format_*helpers are typed to return their item TypedDict viacast(...)at thefilter_none_valuesboundary (resolves list-invariance under pyright).TestTypedOutputSchemaslocks theNotRequireddecisions into CI. - Read-only launch mode:
MORGENMCP_READ_ONLY(truthy env) or--read-only(CLI flag, parsed inmain()) callsmcp.disable(tags={"write", "delete"})once at startup, beforemcp.run()(_apply_read_onlyinserver.py). This hides + disables every mutating tool, leaving the reads. The tag taxonomy is a complete gate (every mutating tool carrieswriteordelete, verified by tag tests). Applied at startup so the disabled state is in the firstlist_tools— and because listing caches are disabled,disable/enableare reflected immediately (a default-cachedtools/listwould have masked the toggle for 5 min). Disabled tools are both unlisted and uncallable through the protocol. - Datetime fields use LocalDateTime format (
2023-03-01T10:00:00) - no Z suffix; timezone is separate EventCreateResponsehas nested structure:response.event.id, notresponse.id- Timing fields constraint:
update_eventandbatch_update_eventsrequire all four timing fields (start,duration,time_zone,is_all_day) together or none — partial updates are rejected - Alerts: Tools accept negative ISO 8601 offsets (e.g.,
'-PT15M') and convert them to Morgen's base64-encoded alert ID format (base64(JSON({a:'display',to:offset}))).alertsanduse_default_alertsare mutually exclusive. - Recurrence rules: Accept simplified dicts
{frequency, interval, by_day}; thebuild_recurrence_ruleshelper converts to JSCalendarRecurrenceRuleobjects. - Tags endpoint quirk:
/tags/listreturns a bare JSON array, not the standard{data: ...}envelope — the client handles both shapes. - Never rely on Morgen's server-side list defaults (
resolve_limitinclient.py)./tasks/listreturns 1 task whenlimitis omitted — that is Morgen's documented, intentional default, andtasks.mdxcarries a warning telling callers to always set the parameter explicitly. So the client always sends one.TASKS_DEFAULT_LIMIT = 100is therefore MorgenMCP's own choice, not a mirror of Morgen's default: it shields callers from a near-empty response that is easy to misread as "no tasks".limithandling still differs per endpoint because the docs differ: tasks documents default 1 / max 100, solist_tasks_and_spacessends its own default and the tool rejects >100; tags documents neither ("Returns all tags"), solist_tagsomits the parameter and enforces no ceiling. Do not "harmonize" the two — hardcodinglimit=100inlist_tagswould introduce truncation past 100 tags. Resolution order is per-call arg > CLI flag > env var > MorgenMCP default; a malformed or out-of-range env var raises at startup rather than silently under-returning. - HTTP client hardening (
client.py):_RetryAfterTransportretries a request once when Morgen answers 429 with a shortRetry-After(≤10s; longer hints and the HTTP-date form surface the 429 immediately). The transport wraps a realAsyncHTTPTransportwithLimits(max_connections=10)andretries=1(connect errors), so respx still intercepts in tests. Timeouts are split (Timeout(30, connect=10)). Upstream error bodies are truncated to 300 chars (_truncate_error_text) before landing inMorgenAPIError/ToolError— a 5xx HTML page or data-echoing body must not reach the LLM verbatim. - Bounded batch concurrency: every batch/fan-out
asyncio.gathergoes throughgather_bounded(tools/utils.py, semaphore,BATCH_CONCURRENCY = 8, alwaysreturn_exceptions=True). Applies tobatch_delete_events,batch_update_events,batch_delete_tasks, the per-account fan-out intools/events.py::list_events, andresources.py::_fetch_events_in_window(backing everymorgen://events/*andmorgen://calendar/{id}/eventsresource). Never add a bareasyncio.gatherover per-item API calls. - Startup fail-fast:
_require_api_key(server.py) rejects a missing/blankMORGEN_API_KEYboth inmain()(clean argparse error) and at the top of the lifespan (covers programmatic use). Without it the server would start, advertise all tools, and fail lazily on the first call. - No raw Morgen IDs in client-visible text: warnings/errors surfaced via
ctx.warningorToolErrormust reference virtual IDs (register_id(...)) — raw calendar/event IDs base64-decode to email addresses. - EventUpdateRequest.alerts uses
dict[str, Alert | None]to support patch-style removal (set entry toNoneto delete that alert).EventCreateRequest.alertsuses the same widened type for consistency at type-check time, even though create never accepts None values. - Display timezone for compact events:
_format_compact_eventconverts event times into a display tz resolved by_resolve_display_tz: explicitdisplay_timezonearg onmorgen_list_events→MORGENMCP_DISPLAY_TZenv var → system local timezone. Every compact line includes aMMM DDdate prefix so multi-day listings remain scannable. Rendered lines look like"Jul 15 09:15-10:00 CDT (America/Chicago): Standup [abc123]". All-day events render as"Jul 15 (all-day): Holiday [abc123]". Floating events (time_zone=None) are tagged(floating)and not converted. Cross-midnight conversions get a date prefix on the end side as well. Resources have no per-call argument path — they rely on env/system fallback only. - Compact event kind tags (
_classify_eventintools/events.py): a compact line may carry a kind tag inside the ID brackets —[abc123 task](metadata.taskId),routine(metadata.canBeCompleted),flexible(metadata.isAutoScheduled),free(freeBusyStatus == "free"), or a comma-joined pair such as[abc123 task,free](no space after the comma). The tag lives inside the brackets deliberately: an earlier{tag}-before-[id]form could be spoofed by a title ending in a brace-word ("Board meeting {free}"on a busy event rendered byte-identically to a genuinely free one, so a client would schedule over a hard conflict). Inside the brackets, a spoof would require forging the 7-char virtual ID. The first three are mutually exclusive and evaluated in that order;freeis orthogonal. An ordinary busy event is deliberately untagged — it was 79% of a 339-event live listing, and compact mode exists to save tokens, so absence means "normal commitment". Applied at all five_format_compact_eventreturn sites (all-day, floating, bad-tz, normal, parse-failure) so the format is uniform, and inherited by all four event resources via_events_payload(morgen://events/today,/this-week,/upcoming, plusmorgen://calendar/{id}/events). Parsing: match the trailing[<7-char id>( <tag>)?]at end of line. Titles may contain braces and brackets (9 of 388 real titles contain[...]), so anchor on the line end; never test for a tag withassert "{" not in result. - Undocumented
morgen.so:metadatafields:canBeCompleted,isAutoScheduledandisFlexibleare returned by the live API on every event carrying a metadata object, but appear in no commit of the docs repo and not on docs.morgen.so. Their meaning comes from Morgen's product docs:canBeCompletedmarks a Routine — a recurring block you check off, "displayed like tasks but do not clutter the task sidebar" — and is mutually exclusive withtaskIdupstream ("An event with canBeCompleted cannot have a taskId"), which is why the classifier falls throughtask→routine. All three are modeledbool | None = Noneso "absent" stays distinguishable from "explicitly false"; if Morgen drops one, its tag silently stops appearing rather than erroring.isFlexibleis modeled but nothing classifies on it — it wasfalseon all 459 probed events and its meaning is unconfirmed. Do not modelframeFilterMql: it embeds raw Apple Reminders list UUIDs, and leaving it unmodeled keeps Pydantic'sextra="ignore"dropping it. morgen.so:metadatais writable on create, despite being documented read-only.events.mdx:201calls it "Read-only Morgen-specific metadata", but a live probe (2026-09-11) created an event with"morgen.so:metadata": {"canBeCompleted": true}and Morgen accepted it (HTTP 200) and echoed it back. SettingcanBeCompletedalso causes Morgen to auto-populateprogress: "needs-action"— the completion-tracking field — confirmingcanBeCompletedis the "check-off-able" flag.canBeCompletedis metadata-only: sent as a top-level field it is rejected with"property canBeCompleted should not exist"(create whitelists properties rather than ignoring unknowns). Treat this as doc drift, not a guarantee: it is undocumented behavior that could change.- Routines expand like any recurring event. A recurring routine (
recurrenceRules+metadata.canBeCompleted,countis accepted) expands to one event per occurrence, and every occurrence carriescanBeCompleted: trueindependently — so_classify_eventtags each one{routine}with no master-event lookup. Each occurrence gets its ownid(and so its own virtual ID) plus a sharedmasterEventIdand its ownrecurrenceId. Note occurrences reportisRecurring: falsein full output, because_format_full_eventderives that fromrecurrence_rules, which the expanded occurrences do not carry — the series is identified bymasterEventId/recurrenceIdinstead. Deleting the whole series isPOST /events/delete?seriesUpdateMode=allwith the master id; it returns 204 with an empty body. Creating one is also possible via the API (recurrenceRules+metadata.canBeCompleted);countis accepted in the rule. canBeCompleted+taskIdis rejected upstream with HTTP 400"An event with canBeCompleted cannot have a taskId"— reproduced first-hand on 2026-09-11, not just reported by third parties. This is why_classify_eventfalls throughtask→routine: the two cannot co-occur, so the ordering is a tiebreak Morgen can never actually exercise.- Completing a routine does not clear
canBeCompleted. A checked-off routine keepscanBeCompleted: trueand setsprogress: "completed"(verified by read-back; note the/events/updateresponse returnsmorgen.so:metadata: null, so re-read from/events/listrather than trusting the update echo). The{routine}tag therefore persists after check-off — it marks what the item is, whileprogresscarries done-ness. This is whyprogressis surfaced in full output. isRecurringis wrong for expanded occurrences (pre-existing, not introduced by the kind-tag work):_format_full_eventderives it fromrecurrence_rules, which occurrences do not carry, so every occurrence of every recurring event reportsisRecurring: false. The series is identified bymasterEventId/recurrenceIdinstead. Fixing it means deriving from those fields; left alone here to keep the tag change scoped.
Morgen API ID Structure
Calendar/event IDs are base64-encoded JSON arrays with embedded relationships:
- Account ID: MongoDB ObjectId (24 hex chars)
"507f1f77bcf86cd799439011"
- Calendar ID:
base64([accountId, calendarEmail])"WyI1MDdmMWY3N2JjZjg2Y2Q3OTk0MzkwMTEiLCJ1c2VyQGV4YW1wbGUuY29tIl0"- Contains account ID at index 0
- Event ID:
base64([calendarEmail, eventUid, accountId])"WyJ1c2VyQGV4YW1wbGUuY29tIiwiZXZ0XzEyMzQ1Njc4OTAiLCI1MDdmMWY3N2JjZjg2Y2Q3OTk0MzkwMTEiXQ"- Account ID at index 2, calendar email at index 0
- Calendar ID can be reconstructed:
base64([accountId, calendarEmail])
This allows deriving account_id and calendar_id from event_id without caching.
Tasks and tags use opaque IDs — base64 strings (tasks) and UUIDs (tags) without embedded structure. They go through the same virtual-ID layer but require no extraction utilities.
Virtual IDs
Tools expose 7-character Base64url virtual IDs (e.g., aB-9xZ_) instead of raw Morgen IDs for token efficiency. The id_registry module handles mapping between virtual and real IDs. Character set: A-Za-z0-9-_.
Virtual IDs are deterministic (MD5(real_id)) and persisted to disk via py-key-value-aio's FileTreeStore. Reads are sync in-memory dict lookups; writes are fire-and-forget async write-through to the store. On startup, the server lifespan loads all persisted mappings into memory, so IDs survive server restarts without re-listing.
- Storage location:
~/Library/Application Support/morgenmcp/id_store/(viaplatformdirs.user_data_dir),chmod 0o700after setup — persisted entries hold raw Morgen IDs, which decode to email addresses - Override: Set
MORGENMCP_DATA_DIRenv var to use a custom directory - Graceful degradation: If the store fails to initialize, the server continues with in-memory-only IDs (session-scoped)
- Tests: Persistence is disabled by an
autouseconftest fixture (set_store(None))
Stability contract: The hash output is governed by HASH_SPEC in id_registry.py — algorithm (MD5), input encoding (UTF-8), digest slice (6 bytes), output length (7 chars Base64url, no padding). The contract is published to MCP consumers via the morgen://server resource and pinned by tests/test_id_persistence.py::TestVirtualIdGoldenVectors. The current scheme version is HASH_SCHEME_VERSION = 1.
What is hashed: the raw real_id string exactly as Morgen returns it. Not a Pydantic model, not a JSON-serialized envelope. UTF-8 encoded. See the reference_implementation field in HASH_SPEC for the canonical one-line expression — a downstream consumer can reimplement it and verify against the test_vectors map.
When (and only when) it is OK to break the hash: Bump HASH_SCHEME_VERSION in the same commit that changes the output. Never reuse a version. Consumers detect the change by re-reading morgen://server between sessions; a bumped scheme_version signals that any stored virtual ID is stale and must be re-resolved by calling the relevant list_* tool. The persisted store under ~/Library/Application Support/morgenmcp/id_store/ survives the bump (old IDs still resolve from disk), but new registrations for the same real ID will diverge — plan a migration (e.g. one-shot store wipe + re-list on startup) in the same PR.
Environment variables
MORGEN_API_KEY: Required. Morgen API key. Checked at startup (_require_api_key) — the server refuses to start without it instead of failing lazily on the first tool call.MORGENMCP_DATA_DIR: Override the virtual-ID persistence directory.MORGENMCP_DISPLAY_TZ: IANA timezone (e.g.America/Chicago) for rendering compact event times inmorgen_list_events(whencompact=True) and allmorgen://events/*resources. Defaults to the system local timezone. Overridden per-call via thedisplay_timezonearg onmorgen_list_events.MORGENMCP_TASKS_LIMIT: Defaultlimitsent to/tasks/listwhen a caller does not pass one. Integer 1-100 (tasks.mdx's documented maximum); defaults to 100. Equivalent CLI flag--tasks-limit N, which wins over the env var. An invalid value fails at startup with an argparse error.MORGENMCP_TAGS_LIMIT: Defaultlimitsent to/tags/list. Integer >= 1, no upper bound (tags.mdxdocuments no maximum). Unset omits the parameter entirely, which returns all tags. Equivalent CLI flag--tags-limit N, which wins over the env var.MORGENMCP_READ_ONLY: Truthy (1/true/yes/on, case-insensitive) launches the server read-only: all mutating tools (everything taggedwriteordelete— the create/update/delete/complete/reopen/move/batch tools) are disabled, leaving only the read tools. Equivalent to the--read-onlyCLI flag (uv run morgenmcp --read-only); either one enables it. Applied once at startup, beforemcp.run(), so the disabled state is baked into the firstlist_toolsresponse.
Testing
- Tool tests (
test_tools.py): Mock viapatch("morgenmcp.tools.*.get_client") - Client tests (
test_client.py): Mock HTTP via@respx.mockdecorator on test methods - MCP protocol tests (
test_mcp_server.py): In-memory protocol-level tests usingfastmcp.Client(mcp)— verifies tool registration, annotations, and end-to-end call flow. UsesMORGENMCP_DATA_DIR=tmp_pathto isolate the persistent store. - Persistence tests (
test_id_persistence.py): Tests FileTreeStore write-through and cross-session restore using real temp-dir-backed stores - Integration tests (
test_integration.py): Hit real API, excluded from CI via pytest marker
Environment
- Python
>= 3.12(set inpyproject.toml) fastmcp>=3.4,<3.5— pinned to 3.4.x patch range
Versioning & Release
Versions are managed via git tags.
git tag -a v0.2.1 -m "Release v0.2.1"
git push origin v0.2.1Pushing a tag triggers .github/workflows/release.yml, which runs tests, builds wheel and sdist distributions, creates a GitHub Release, and publishes to PyPI via Trusted Publishing. Users can run the server via uvx morgenmcp or pin a version with uvx morgenmcp==<version>.
Documentation Resources
IMPORTANT: Always use the local docs submodules as the primary source of truth. They are version-pinned to match the exact dependency versions in this project. Online docs may describe newer or older API versions that do not match what this project uses. Only fall back to online docs when local docs are insufficient.
Caveat — verify any doc claim that drives a code change. The Morgen docs are
the right starting point and beat online sources, but they are not always
authoritative about runtime behavior. /tasks/list's documented default was
wrong for months — it claimed 100 while the endpoint returned 1 — and was
corrected upstream only in 616aeed (MOR-4652), which is why this repo's
limit handling carries so much explanatory comment. The submodule now tracks
the docs repo's main rather than a feature branch, but it can still run ahead
of or behind what is deployed. Confirm doc-driven claims with a read-only probe
against the live API where that is cheap.
When spawning Explore agents, always include this instruction in the prompt: "For Morgen API questions, search docs/morgen-dev-docs/content/ first. For FastMCP questions, search docs/fastmcp/docs/ first. These local docs match the pinned dependency versions and take priority over online sources."
Local docs (primary — version-pinned, must be initialized)
| Source | Path | Covers |
| Morgen API | docs/morgen-dev-docs/content/*.mdx | Endpoints, parameters, schemas, changelog |
| FastMCP | docs/fastmcp/docs/ | Server framework: tools, context, auth, testing, deployment |
- Morgen docs submodule: pinned at
e2fb838(docs repomain) - FastMCP docs submodule: pinned at
1eedd1f6(v3.4.3, matching thefastmcp>=3.4,<3.5pin); clonedshallow = true, so it carries no tags andgit describewill fail
These are git submodules and are NOT populated by a fresh clone. Nothing updates them automatically — there is no hook that does this. Check and initialize them before relying on any lookup rule below:
git submodule status # a leading '-' means uninitialized/empty
git submodule update --init # populate bothAn uninitialized submodule is an empty directory, so a grep over
docs/morgen-dev-docs/content/ silently returns nothing rather than erroring.
Treat "no matches" as "check git submodule status first", not as "the docs
don't cover it" — otherwise every rule in this section quietly degrades to
guessing from memory or reaching for the live API.
Online docs (fallback only)
| Source | URL | When to use |
| Morgen API | https://docs.morgen.so/ | Only if local MDX files lack the endpoint or field you need |
| FastMCP | https://gofastmcp.com/llms.txt | Only if local docs under docs/fastmcp/docs/ don't cover the topic |
| MCP Protocol | https://modelcontextprotocol.io/llms.txt | Protocol spec: transports, tool schema, JSON-RPC messages (no local copy) |
Lookup rules
- Before implementing or modifying any tool: Search
docs/morgen-dev-docs/content/*.mdxdirectly (grep for the endpoint or resource name, read the matching file) to confirm parameters, required fields, and response shapes. Only cross-reference online docs if the local result is incomplete. - For FastMCP patterns (tool registration, return types, error handling, testing): Search
docs/fastmcp/docs/directly — grep for the pattern (decorator,Contextmethod, error class, testing helper) and read the matching file for file paths, line numbers, and code examples. These docs match the installed FastMCP version exactly. - For MCP protocol questions (transport, JSON-RPC, tool schema): Fetch
https://modelcontextprotocol.io/llms.txtfirst, then the relevant spec page (no local copy exists). - When adding a new tool or changing tool signatures: Check both FastMCP local docs (for decorator/return-type patterns) and the MCP protocol spec (for schema requirements) to ensure compliance.
- When spawning any agent (Explore, Plan, or general-purpose) that may need API or framework information: Include the local doc paths in the prompt (
docs/morgen-dev-docs/content/for Morgen API,docs/fastmcp/docs/for FastMCP) so the subagent searches them directly rather than guessing or using online sources.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

