Building a client

Documentation Index

Fetch the complete documentation index at: https://docs.myme.so/llms.txt

Use this file to discover all available pages before exploring further.

​

Anatomy of a client

1. A credential. One API key (or OAuth grant) with scoped permissions.
2. An SDK connection. Typically the TypeScript or Swift SDK, instantiated once and reused.
3. An entry point. A CLI command, an MCP tool, an HTTP handler, a scheduled task.

​

Worked example: @withmarfa/mcp

​

Skeleton

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { MarfaClient } from "@withmarfa/sdk";

const client = new MarfaClient({
  url: process.env.MARFA_API_URL!,
  apiKey: process.env.MARFA_API_KEY!,
});

const server = new McpServer({ name: "marfa", version: "x.y.z" });

server.tool(
  "create_item",
  { /* JSON schema for tool input */ },
  async (input) => {
    const item = await client.items.create(input);
    return { content: [{ type: "text", text: JSON.stringify(item) }] };
  }
);

// ... register the rest of the tools ...

await server.connect(new StdioServerTransport());

​

The whole client is thin

1. Parses input according to a tool-specific schema.
2. Calls one SDK method.
3. Returns the result as JSON.

​

Credentials and scope

​

LLM-friendly tool descriptions

• Use the actual type and edge names (core.note, in-thread, parent-of) — the LLM has seen them in these docs.
• Describe what a field does, not just its type. “tier: library | feed — curated library vs high-volume feed” is useful; “tier: string” alone isn’t.
• Call out enum values explicitly. “state: active | archived | trashed” beats “state: string”.

​

Patterns by client kind

​

Interactive app (iOS, macOS, web)

• Use the SDK in the app’s data layer. Map SDK types into your view models.
• For long-running UIs, subscribe to /events via the SDK’s SSE iterator. Update the view model when events arrive for items you’re displaying.
• Store the API key (or OAuth tokens) in the platform’s secure store (Keychain on Apple, Credential Manager on web).

​

CLI

• Load the API key from MARFA_API_KEY or a config file (~/.config/marfa/config.toml).
• Provide one command per meaningful workflow: my items list, my items create, my import. Thin wrappers around SDK calls.
• Print results as tables for humans, JSON for machines (controlled by --json or detecting non-TTY stdout).

​

Ingest agent / sync daemon

• Long-running process with a single API key scoped to the types it writes.
• For pull-based syncs: a scheduled loop calling GET /items?source=X&updated_after=....
• For push-based: watch the source (a folder, a feed, an inbox) and POST /items as new data appears. Set source_id on each item — the server resolves (source, source_id) as a natural key, so re-posts upsert rather than duplicate. See Items — natural-key upsert.
• Set default_tier=feed on the credential — ingested items typically land in the high-volume feed slice, not the curated library.

​

MCP server

• Pattern above. Thin, stateless, one tool per SDK method.
• Run under the LLM host’s process manager (Claude Desktop, Claude Code, Goose).

​

Integration / webhook consumer

• Register a webhook via client.webhooks.create.
• Accept webhook POSTs, verify the HMAC signature, process asynchronously.
• No need for an SDK on the webhook-receiving side unless you’re calling back into Marfa from the handler.

​

Optional titles

• Leave null, derive at render. Persist title: null. Compute a display title from the first line of body at render time. Simplest; follows body edits naturally; nothing to keep in sync.
• Derive on save, persist. Compute a title from the body on each save and write it into title. Other apps see the title directly without needing to know the derivation rule.
• Leave blank. Don’t derive. Other apps fall back to body content when they need a display string.

​

What doesn’t go in Marfa

• App settings. Theme, default model, UI preferences, layout state. They have no cross-app meaning. Use the OS’s normal mechanism — UserDefaults on macOS, localStorage on web, iCloud Key-Value Storage if cross-device sync is wanted.
• Sync cursors. A sync agent’s per-root cursor is agent-local state. It lives on the agent’s own disk, not on any item in the platform. Same for crawlers, scrapers, or any client tracking external-source position.
• Ephemeral session state. Current scroll position, undo stack, in-flight network state. Stays in the app’s memory.

​

What clients should not do

• Don’t cache item contents across sessions without a sync mechanism. If your client is long-lived and needs reactive state, use SSE; don’t roll a stale-check poll.
• Don’t re-implement permissions client-side. The server enforces; your job is to surface what the server returned.
• Don’t hide error codes from callers. Propagate MarfaError (or its localized equivalent) — don’t wrap in generic errors that lose the code.
• Don’t hard-code tenant ids. They’re implicit from the credential; URLs never carry them.

​

Testing a client