Introducing a new way to review your PRs.

Read the announcement

usememos / memos

Memos is an open-source, self-hosted note-taking app that brings your everyday thoughts together in a personal timeline. Your data stays yours, and you choose what to keep private or share.

View on GitHub

25 documents · Updated Nov 20, 2026

docs / mcp-rss-and-file-delivery

MCP, RSS, and file delivery endpoints

Memos exposes several delivery interfaces beside its main API. The Model Context Protocol (MCP) endpoint gives agents a controlled catalog of memo, attachment, and space tools. The frontend service serves the browser application, while the RSS and file services deliver public feeds and protected media. These interfaces share the same server and access rules, but each one shapes content for a different client.

See Server runtime and routing for the full request path, API contracts and services for the API boundary, and Attachment and object storage for storage choices behind file delivery.

Delivery interface map

The server registers these interfaces on one HTTP listener. A request reaches the interface that owns its path, and that interface then applies the access policy needed for its content.

InterfaceMain pathsClient purposeAccess shape
MCP/mcpLet an AI client discover and call selected memo, attachment, and space operationsTool calls use the caller's authorization and the API's access checks
RSS/explore/rss.xml, u/…/rss.xmlLet feed readers follow public memo contentAvailable for public instances and public memo content
Frontend/, extensionless browser paths, static assetsLoad and navigate the web applicationPublic shell and assets; discovery documents follow instance access policy
Files/file/attachments/..., /file/users/.../avatarLoad media, documents, thumbnails, motion clips, and avatarsAttachment and user permissions apply before bytes are sent

MCP interface

The MCP interface presents a small, agent-focused view of the API. It uses the embedded OpenAPI contract to describe tools and sends each accepted call through the server's existing API routes, so MCP clients receive the same resource behavior rather than a second data path.

Tool catalog

The catalog contains 36 curated tools. It focuses on memo work, attachments, spaces, and related read actions instead of exposing the full account, administration, AI, identity, sharing, or webhook surface. The service builds this fixed catalog at startup and fails to start if a selected operation, a duplicate tool name, or an operation-specific rule no longer matches the OpenAPI contract.

The catalog covers these capability groups:

  • Memo listing and create, read, update, and delete actions.
  • Memo comments, attachments, reactions, and relations.
  • Attachment listing, creation, reading, and deletion.
  • Memo view listing for reusing a user's saved filters.
  • A read-only current-user lookup for resolving the caller's identity.
  • Space discovery and management, membership, and invitation handling.

Each tool has an input schema and an output schema derived from the API description. The catalog also marks read-only, destructive, and idempotent behavior so an agent can choose actions with better safety signals. These annotations guide clients but do not replace API authorization.

References: server/…/catalog.go• L12-54 server/…/catalog.go• L81-134 server/…/catalog.go• L179-200 server/…/catalog.go• L349-381 server/…/catalog_test.go• L13-37 server/…/catalog_test.go• L451-544

Tool request handling

Clients call the stateless Streamable HTTP service at /mcp. The service returns JSON responses and does not keep MCP sessions. It checks the request origin before handing the request to the protocol handler. An empty origin is accepted. A supplied origin must match the request host or the host in the configured instance URL. This protects browser-based calls without rejecting a deployment where the process listens on a local address behind a public proxy.

The service applies the API-wide request size limit, including for attachment uploads. Its catalog responses carry a 24-hour freshness hint because the tool set is fixed after startup. The service does not advertise tool-list change notifications.

The request flow has four stages:

  1. The client sends a tool call with JSON arguments and may include an Authorization header.
  2. MCP validates the arguments against the catalog schema.
  3. The adapter builds an in-process API request. It forwards authorization and the resolved client address.
  4. The API response becomes structured tool content. API failures become MCP tool errors.

Path arguments accept either a bare resource ID or its canonical resource name. For nested resources, the adapter removes a canonical prefix only when it matches the already resolved parent path. This lets agents use API resource names without changing the API route or binding a resource to the wrong parent.

This relationship keeps authentication, rate-limit identity, and resource rules in the API layer. An MCP client can act only within the permissions of the token or session that it sends.

This diagram shows how an agent call keeps the MCP boundary thin and returns to the normal API path for business rules.

sequenceDiagram
    participant A as MCP client
    participant M as /mcp service
    participant V as Tool schema validation
    participant G as In-process API routes
    participant D as Store and access rules

    A->>M: tools/list or tools/call
    M->>M: Check Origin and request size
    M->>V: Validate tool arguments
    V-->>M: Accepted arguments
    M->>G: Build API request with authorization and client address
    G->>D: Apply API behavior and access checks
    D-->>G: JSON response or API error
    G-->>M: Response value
    M-->>A: Structured result or tool error

References: server/…/service.go• L19-28 server/…/service.go• L38-97 server/…/service.go• L100-117 server/…/service.go• L131-165 server/…/adapter.go• L29-105 server/…/adapter.go• L107-211 server/…/service_test.go• L115-190 server/…/service_test.go• L607-821

OpenAPI tool schemas

MCP exposes self-contained JSON Schema so clients can validate tool calls without loading the full API document. The service resolves the selected operation's request and success-response schemas and keeps nested component links in local definitions. Attachment content is described as base64 data.

The catalog adjusts schemas where the API meaning is more precise than a shared resource schema. Create actions require the content they need. Partial updates require at least one changed field. Path-bound operations do not ask the agent to repeat the resource name in the body. These rules reject invalid calls before they reach the API.

Successful results use an object-shaped structured result. Object responses pass through. Empty responses become an ok result. Arrays or scalar values are placed under a result field. Error results omit success content so strict clients do not validate an error against the success schema.

This schema boundary keeps the agent contract tied to the API contract. A change to an operation name, path, request body, response, or schema format can therefore affect service startup or the shape that MCP clients send and receive.

References: server/…/catalog.go• L255-329 server/…/catalog.go• L369-413 server/…/adapter.go• L29-47 server/…/adapter_test.go• L19-60 server/…/catalog_test.go• L44-108 server/…/catalog_test.go• L189-209 server/…/catalog_test.go• L396-449 server/…/service_test.go• L532-605

MCP task evaluations

The MCP evaluation set checks whether an agent can complete realistic read-only tasks by combining the curated tools. It complements unit tests for the server plumbing by checking tool descriptions, discoverability, and multi-call reasoning against a stable data set.

The evaluation uses 15 independent questions with one comparable answer each. Questions 1–10 exercise memo tools. Questions 11–15 exercise space tools and memo placement. It must run against a fresh seeded demo instance because the public demo is shared and changes over time. The seed includes memos, reactions, spaces, and one attachment, but no saved memo views or pending invitations, so evaluation questions must match that data shape.

The evaluation flow starts a throwaway SQLite demo instance, sends an authenticated client to /mcp, and compares each model answer with its expected string. The seed uses relative timestamps, so questions rely on stable ordering, counts, and content instead of fixed dates. When the seed changes, the answers and this evaluation summary must change together because the evaluation does not detect drift automatically.

References: server/…/README.md• L1-14 server/…/README.md• L16-41 server/…/README.md• L43-71 server/…/memos_eval.xml• L1-21 server/…/memos_eval.xml• L22-83

RSS feeds

RSS provides a machine-readable view of public memo content for feed readers and other clients that do not use the API or web application. The service exposes an instance-wide explore feed and a per-user feed, renders memo content as HTML, and uses cache validation so clients can avoid downloading unchanged content.

RSS is available only when the instance permits anonymous access. The feeds include public memos rather than private or restricted content. If the instance is private, the feed routes return not found instead of revealing that a feed exists.

References: server/…/rss.go• L65-174

Frontend serving

The frontend service makes the browser application available from the same HTTP server as the API. It serves the built application files and uses a single-page application fallback so a browser can open a client-side route directly.

Application shell and assets

The service serves static frontend files from the embedded application bundle. Requests for /, /index.html, and paths without a file extension can fall back to index.html when no more specific route handles them. This lets the browser router own navigation after the initial page load.

Frontend middleware does not claim API, file, or discovery paths. Those paths remain available to their own services. HTML is not cached so new application shells can reach clients. Ordinary assets use a one-hour cache, while assets under /assets/ use a longer immutable cache intended for hashed files.

References: server/…/frontend.go• L20-27 server/…/frontend.go• L41-109

Discovery documents

The frontend service also provides /robots.txt and /sitemap.xml. Both documents require anonymous access and use the configured instance URL. The robots document points crawlers to the sitemap. The sitemap lists URLs for public memos only.

If the instance URL is missing, the service cannot form valid public links and returns 404 Not Found. If anonymous access is disabled, public discovery is unavailable and also returns 404 Not Found.

References: server/…/frontend.go• L123-191 server/…/frontend.go• L194-205

Attachment file serving

The file service turns attachment and avatar records into HTTP responses. It checks access from attachment metadata before it reads or streams attachment bytes, then chooses a response suited to the content. This gives the web client one stable URL shape even when the underlying bytes use different storage backends. Storage choices and object access are described in Attachment and object storage.

Attachment access and response paths

Attachments are available at /file/attachments/:uid and at the same path with an optional filename segment. The service first finds the attachment metadata and checks the linked memo's own read permission before it loads database-stored bytes or streams content. An attachment on a comment follows that comment's visibility rather than the parent memo's visibility. A linked public memo can be read anonymously when the instance allows it. A share token can grant access only to the memo named by that share. An unlinked attachment is limited to its creator or an administrator.

The response uses private, non-storing cache behavior by default and switches to public revalidation when the access decision is public. Public access does not become an authentication error because of a stale browser credential. The service sends security headers for file responses. Unsafe active-content types are sent as downloads with a safe content type instead of being allowed to execute in the browser. Storage failures keep the JSON error envelope instead of being mistaken for the attachment's media type.

References: server/…/fileserver.go• L137-198 server/…/fileserver.go• L151-185 server/…/fileserver.go• L690-765 server/…/fileserver_test.go• L125-193 server/…/fileserver_test.go• L195-291 server/…/fileserver_test.go• L334-389 server/…/fileserver_test.go• L437-502 server/…/fileserver_test.go• L758-879 server/…/fileserver_test.go• L882-985

Media and derived content

Images and documents are returned as ordinary file responses. Video and audio use streaming with byte-range support so players can seek without loading the full file into memory. This behavior applies whether the bytes come from local storage, object storage, or the database-backed fallback. Unsupported multi-range requests can fall back to a complete response, while an invalid single range returns 416. A missing local file or object storage read returns the normal JSON error response.

Image requests can ask for a thumbnail with ?thumbnail=true. Motion-photo requests can ask for an extracted video clip with ?motion=true. These derived responses are cached on the server after generation. The service limits thumbnail work and refuses oversized or unsuitable source images rather than repeatedly decoding them. It remembers only a confirmed unsupported-image result; a temporary storage read failure is retried later. If a thumbnail would lose important image metadata, the service uses the original image instead.

Avatars use /file/users/:identifier/avatar. Public instances can serve them to anonymous users. Private instances require an authenticated request before the avatar is read, and private responses are not stored by shared or browser caches.

References: server/…/fileserver.go• L201-249 server/…/fileserver.go• L255-305 server/…/fileserver.go• L327-424 server/…/fileserver.go• L445-617 server/…/fileserver.go• L632-684 server/…/fileserver_test.go• L75-123 server/…/fileserver_test.go• L391-435 server/…/fileserver_test.go• L504-677 server/…/fileserver_test.go• L1051-1069 server/…/fileserver_test.go• L1134-1194

Change checklist

When these files or sections are changed, remember to consider these:

  • Update the MCP catalog and its schema or safety annotations when an API operation ID, path, request body, or response contract changes. A stale catalog can fail service startup or expose the wrong tool shape.
  • Keep the evaluation seed and question assumptions aligned. A question that depends on mutable demo data or on absent memo views and invitations can give a false signal.
  • Keep the stateless MCP transport contract aligned with client protocol discovery. Changes to session methods, capability flags, or catalog freshness can make newer clients cache stale tools or reject the endpoint.
  • Keep the MCP request limit equal to the API limit. A smaller SDK limit can reject attachment uploads before the API handles them.
  • Preserve resource-name handling when changing API paths. Canonical nested names must bind only to their matching parent route.
  • Review anonymous-access behavior together for discovery documents, public attachments, and avatars. These interfaces must not publish data after the instance changes to private access.
  • Keep file attachment authorization aligned with the API's unlinked-attachment rule. The creator and an administrator can read an unlinked attachment; other authenticated users cannot.
  • Keep attachment authorization tied to the memo that owns the attachment. A share for a parent memo must not grant access to an attachment on a protected comment.
  • Preserve the JSON error envelope when a local file or object storage object is missing. The attachment media type must not hide the actual storage error.
  • Preserve the frontend exclusion rules when adding a delivery route. A new non-frontend endpoint can be hidden by the SPA fallback or receive frontend cache headers.
  • Keep media range behavior aligned across local and object storage. A change that removes Accept-Ranges or Content-Range can break video and audio seeking.
  • Keep thumbnail failure caching limited to unsupported image data. A transient storage error must remain retryable.

Important failure modes

TriggerConsequenceGuard
MCP origin differs from the request host and configured instance URLThe request is rejected with 403 ForbiddenUse the public instance origin in browser clients or send no origin from non-browser clients
A curated MCP operation or override is removed or renamed without updating the catalogMCP service creation fails instead of serving a partial catalogKeep operation IDs and catalog overrides in sync with the API contract
A tool schema uses an API-only format or returns a non-object success valueStrict MCP clients reject discovery or result validationKeep schemas client-safe and preserve the object-shaped result envelope
An MCP client sends a request larger than the API-wide limitThe request is rejected with 413 Request Entity Too Large, including before tool handling when its declared size is too largeKeep client payloads within the shared API limit
A client uses stateful MCP session methods against the stateless endpointThe endpoint rejects session streaming or teardown methodsUse JSON request and response calls supported by the stateless transport
An MCP evaluation runs against the shared public demoAnswers do not match the expected seed and the evaluation gives a false failureRun evaluations against a fresh seeded demo instance
A frontend path is mistaken for a delivery pathThe SPA shell can be returned instead of the expected API or file responseAdd the path to the frontend skip rules and register its owning route
An attachment is private, unlinked, or bound to a different memo than the share tokenThe file bytes are not returnedUse the memo's allowed read path, a valid matching share token, or an authenticated owner or administrator request
A media client sends an unsupported or unsatisfiable rangeThe client gets a full response for unsupported multi-range input or 416 for an invalid rangeUse one valid byte range and handle 206, 200, and 416 responses
Thumbnail input exceeds the decode budget or cannot preserve required metadataThe original image is served and a bad image is not decoded again on every requestTreat the original-image fallback as the supported result for that attachment
A local file or object storage object disappears after metadata authorizationThe client receives a JSON storage error rather than usable file bytesRestore the backing object or handle the file error response
A thumbnail source has a temporary storage read failureThe original image may be served and later requests can try generation againDo not treat a read failure as proof that the image is unsupported

Key files

FileWhy to read it
server/server.goShows when the frontend, file, API, and MCP services join the shared HTTP server
server/…/service.goShows the stateless MCP endpoint, request limits, catalog freshness, origin gate, and protocol handler
server/…/catalog.goShows the agent-facing tool scope, input rules, and safety metadata attached to tools
server/…/openapi.goShows how API schemas become self-contained MCP input and output contracts
server/…/adapter.goShows how MCP calls become in-process API requests and how authorization, resource names, client address, and results cross the boundary
server/…/README.mdExplains how task-level MCP quality checks use a stable seeded instance
server/…/rss.goShows the public explore and user feed boundary and feed response behavior
server/…/frontend.goShows frontend asset delivery, SPA fallback, cache policy, robots, and sitemap behavior
server/…/fileserver.goShows attachment authorization, media streaming, derived media, avatar delivery, storage errors, and response safety rules