openpetswithchatandmcp/docs/cursor-integration.md

Cursor Integration

FamiliarOS supports Cursor through MCP configuration plus optional project rules. This document is the user and developer reference for the current integration, safety model, implementation files, and future phases.

Current status

Capability	Status	How it works
Cursor MCP tools	Implemented	Cursor runs @familiaros/mcp as a stdio MCP server.
Desktop global setup	Implemented	Desktop Agent Setup manages ~/.cursor/mcp.json, only mcpServers.familiaros.
CLI project setup	Implemented	familiaros configure --agent cursor manages <project>/.cursor/mcp.json.
Project rules	Implemented	familiaros configure --agent cursor --rules-only manages <project>/.cursor/rules/familiaros.mdc.
Global/user rules	Not implemented	Cursor exposes user rules through Settings; FamiliarOS does not assume a safe editable file path.
Hooks / ambient lifecycle reactions	Future phase	Requires a dedicated validation spike before writing hooks config.
Cursor extension/plugin	Future phase	Optional polish after config and hook behavior are proven.

For now, Cursor integration is complete enough for MCP + project guidance. The next feature phase would be Cursor hooks for ambient reactions similar to Claude hooks/OpenCode plugin events.

User setup

Prerequisites

• FamiliarOS desktop app is running.
• Cursor is installed.
• Node/npm are available for published npx mode, or the package is already cached.
• For project-local CLI setup, run commands from the project you want Cursor to use.

Desktop: global Cursor MCP setup

Use this when you want Cursor to see FamiliarOS tools in every Cursor project.

1. Open FamiliarOS desktop.
2. Open Integrations.
3. Choose Cursor.
4. Pick a familiar if desired.
5. Click Install global setup.
6. Restart/reload Cursor or start a fresh chat if Cursor does not pick up the server immediately.

Desktop writes only this global file:

~/.cursor/mcp.json

It manages only:

mcpServers.familiaros

Unrelated Cursor MCP servers and top-level config are preserved.

CLI: project-local Cursor MCP setup

Use this when you want the current repository to own its Cursor MCP config.

familiaros configure --agent cursor --familiar PET_ID

or from another directory:

familiaros configure --agent cursor --cwd /path/to/project --familiar PET_ID

The CLI writes:

<project>/.cursor/mcp.json

--familiar is optional. If omitted, the CLI may prompt from installed familiars through the running desktop app.

CLI: project Cursor rules

Cursor rules tell Cursor when and how to use the FamiliarOS MCP tools safely. They are prompt guidance, not event hooks.

Install or update only the project rule:

familiaros configure --agent cursor --rules-only

Install MCP config and rules together:

familiaros configure --agent cursor --familiar PET_ID --with-rules

Remove only the managed project rule:

familiaros configure --agent cursor --remove-rules

The rules file is:

<project>/.cursor/rules/familiaros.mdc

--rules-only and --remove-rules do not need --familiar and do not need the FamiliarOS desktop app to be reachable.

Force / conflict behavior

FamiliarOS refuses to overwrite unknown user content by default.

Use --force only when you intentionally want to replace the dedicated FamiliarOS entry/file:

familiaros configure --agent cursor --rules-only --force
familiaros configure --agent cursor --familiar PET_ID --with-rules --force

--force is scoped:

• MCP replacement touches only mcpServers.familiaros.
• Rules replacement touches only .cursor/rules/familiaros.mdc.

Backups are created before replace/remove operations.

What Cursor sees

MCP tools

FamiliarOS exposes these tools through @familiaros/mcp:

• familiaros_status
• familiaros_react
• familiaros_say

The expected Cursor MCP entry is strict JSON:

{
  "mcpServers": {
    "familiaros": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@familiaros/mcp@VERSION", "--familiar", "PET_ID"]
    }
  }
}

If no familiar is selected, --familiar PET_ID is omitted and FamiliarOS routes to the default familiar.

Project rule content

FamiliarOS writes a short .mdc rule with managed markers:

---
description: Use FamiliarOS MCP tools for lightweight coding-status feedback.
---

<!-- FAMILIAROS:CURSOR_RULES:START -->
# FamiliarOS status feedback

You may use the FamiliarOS MCP tools as a brief, safe status channel during meaningful coding work.

- Use `familiaros_say` sparingly for major milestones, blocking states, completion, or when review is needed.
- Prefer `familiaros_react` over speech for lightweight progress such as thinking, working, testing, success, or error.
- Keep messages short, user-facing, and safe.
- Do not send prompts, tool input/output, code, logs, stack traces, credentials, private file contents, URLs, file paths, or other sensitive content through FamiliarOS.
- Do not spam every internal step; use FamiliarOS only for meaningful progress changes and continue normally if a status update is unnecessary.
- If FamiliarOS is unavailable, continue the coding task without failing.
<!-- FAMILIAROS:CURSOR_RULES:END -->

FamiliarOS intentionally does not write alwaysApply: true by default to reduce context noise and tool spam.

Cursor behavior and caveats

Global vs project MCP config

Cursor documents:

• Global MCP config: ~/.cursor/mcp.json
• Project MCP config: .cursor/mcp.json

Cursor merges global and project config. Project config takes priority for duplicate server names. FamiliarOS uses the server name familiaros, so a project-local mcpServers.familiaros can override the global FamiliarOS server.

Restart/reload/new chat

Cursor MCP docs and behavior can vary by version and environment. If Cursor does not show FamiliarOS tools after setup:

1. Start a new chat.
2. Reload Cursor.
3. Fully restart Cursor.
4. Verify Node/npm can run the configured npx command.

Rules are included as chat context. A new or refreshed chat may be needed for changed rules to be noticed.

WSL, remote, and devcontainer caveats

FamiliarOS desktop runs on the local OS and the MCP server connects to its local IPC endpoint. If Cursor runs MCP commands inside WSL, a remote host, or a devcontainer, the command may run somewhere that cannot reach the desktop app.

Symptoms:

• Cursor shows MCP connection failures.
• familiaros_status reports the app is unreachable.
• The configured npx or node command is available in one environment but not the one Cursor uses.

Workarounds may require environment-specific command wrappers. FamiliarOS does not currently write WSL/devcontainer-specific MCP entries automatically.

Security and privacy model

FamiliarOS treats Cursor config as user-owned.

MCP config safety

The @familiaros/cursor helpers:

• read strict JSON only;
• cap MCP config files at 256 KiB;
• reject symlinked config files;
• reject non-regular files;
• reject unsafe/symlinked parent paths;
• classify missing, installed, needs-update, conflict, invalid, and error states;
• preserve unrelated MCP servers and top-level fields;
• preview only the FamiliarOS entry by default;
• redact sensitive fields if broader config previewing is needed;
• write with temp files and atomic rename;
• create backups before overwrite/remove operations;
• remove only recognized FamiliarOS-managed entries.

Rules safety

The rules helper:

• writes only <project>/.cursor/rules/familiaros.mdc;
• treats the file as managed only when the exact FamiliarOS frontmatter and a single ordered marker pair are present;
• classifies user-authored content as a conflict;
• caps rule file reads at 64 KiB;
• rejects symlinks, non-regular files, unsafe parents, and dangling symlinks;
• backs up before replacement/removal;
• removes only the managed familiaros.mdc file and leaves .cursor directories in place.

What FamiliarOS does not do

FamiliarOS does not:

• edit Cursor user/global rules settings;
• edit ~/.cursor/permissions.json;
• add broad MCP/tool allowlists;
• write Cursor hooks yet;
• write project rules from desktop without a reviewed project picker;
• include prompts, tool input/output, code, logs, stack traces, credentials, private file contents, URLs, or paths in familiar messages.

Developer implementation map

Shared package

packages/cursor is the pure Node.js package shared by CLI and desktop.

Key files:

• packages/cursor/src/cursor-mcp.ts
  • MCP entry builders.
  • Global/project MCP path helpers.
  • Familiar id and version validation.
• packages/cursor/src/cursor-status.ts
  • MCP config safe read/classification/write/remove planning.
  • Managed FamiliarOS MCP entry detection.
• packages/cursor/src/cursor-previews.ts
  • FamiliarOS-only preview and secret redaction helpers.
• packages/cursor/src/cursor-rules.ts
  • Project rules content builder.
  • Rules status classification.
  • Safe rules install/replace/remove planning.
  • Atomic rules write/remove execution.
• packages/cursor/src/check-cursor.ts
  • Contract coverage for MCP config and rules behavior.

CLI integration

Files:

• packages/cli/src/index.ts
• packages/cli/src/check-cli-contract.ts

Supported Cursor flags:

familiaros configure --agent cursor --familiar PET_ID
familiaros configure --agent cursor --cwd /path/to/project --familiar PET_ID
familiaros configure --agent cursor --familiar PET_ID --with-rules
familiaros configure --agent cursor --rules-only
familiaros configure --agent cursor --remove-rules
familiaros configure --agent cursor --rules-only --force

Important semantics:

• Existing configure --agent cursor remains MCP-only.
• --with-rules, --rules-only, and --remove-rules are mutually exclusive.
• Cursor rules flags are rejected for non-Cursor agents.
• --rules-only and --remove-rules avoid familiar resolution and desktop connectivity.
• --with-rules preflights MCP and rules plans before writing either file, preventing surprising partial setup.

Desktop integration

Files:

• apps/desktop/src/agent-setup.ts
• apps/desktop/src/windows.ts
• apps/desktop/preload.cjs
• apps/desktop/src/check-cursor-desktop.ts
• apps/desktop/src/check-packaging-contract.ts

Desktop behavior:

• global Cursor MCP install/update/replace/remove in ~/.cursor/mcp.json;
• Cursor detail pane with global warning;
• FamiliarOS-only MCP preview;
• project rules preview and copy button;
• no desktop project rules writes;
• no new Cursor rules IPC actions.

Release plumbing

@familiaros/cursor is a public workspace package and is published before packages that consume it.

Relevant files:

• packages/cursor/package.json
• packages/cli/package.json
• apps/desktop/package.json
• scripts/release-npm.mjs
• pnpm-lock.yaml

Validation and review history

Phase 1 MCP

Validated:

• strict JSON assumption for MCP config;
• restart/reload guidance;
• global/project merge and project priority;
• documented stdio fields: type, command, args, optional env, optional envFile;
• direct pinned command strategy: npx -y @familiaros/mcp@VERSION;
• real Cursor MCP smoke on 2026-05-14 with @familiaros/mcp@2.0.6, showing connected with three tools enabled.

Phase 2 rules

Validated from official docs:

• project rules live under .cursor/rules;
• .md and .mdc are documented;
• .mdc frontmatter supports description, globs, and alwaysApply;
• user rules are managed through Cursor Settings, not a documented editable file path;
• project rules do not require permissions file edits.

Implementation was reviewed with Oracle gates:

• Phase 2 spec review;
• core rules helper review;
• CLI phase review;
• desktop preview/copy review;
• final implementation review.

Checks passed during implementation:

pnpm --filter @familiaros/cursor check
pnpm --filter @familiaros/cli check
pnpm --filter @familiaros/desktop check
pnpm check

What is next?

Cursor MCP + project rules are done for now. The next integration phase would be Cursor hooks if we want automatic familiar reactions during Cursor agent lifecycle events.

Before implementing hooks, run a validation spike and record:

• exact hook config file paths and schema;
• global/project hook precedence;
• payload fixtures for relevant events;
• stdout/stderr behavior;
• timeout behavior;
• fail-open/fail-closed behavior;
• workspace trust behavior;
• execution location for local, WSL, remote, and devcontainer setups;
• whether hook commands can avoid leaking prompt/tool/path data.

Until that spike is complete, FamiliarOS should not write Cursor hook config.

Official references

• Cursor MCP docs: https://cursor.com/docs/mcp
• Cursor MCP customization help: https://cursor.com/help/customization/mcp
• Cursor MCP CLI docs: https://cursor.com/docs/cli/mcp
• Cursor Rules docs: https://cursor.com/docs/rules
• Cursor Rules customization help: https://cursor.com/help/customization/rules
• Cursor permissions reference: https://cursor.com/docs/reference/permissions
• Cursor hooks docs: https://cursor.com/docs/hooks.md
• Cursor extension API: https://cursor.com/docs/extension-api