From 4933e5c7b7c8e7935d507844a69f2fc04de43f4c Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sun, 23 Aug 2026 17:52:30 +0000 Subject: [PATCH] docs: add Cursor Cloud environment setup notes Document the new-note MCP server run/build/test caveats, the unreachable private npm registry pinned in the lockfile, and safe sandboxing for the new_note tool for future cloud agents. Co-authored-by: Cursor Cloud Agent --- AGENTS.md | 26 +++++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 5040f0b..5ff949b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -75,4 +75,28 @@ Keep this managed block so 'openspec update' can refresh the instructions. - **少即是多**: 不要在回复中重复用户已知的信息。 - **安全第一**: 修改 `bin/` 或执行系统级命令前，务必解释潜在风险。 -- **配置优先**: 遇到路径、环境问题，优先检查 `.env` 或配置文件，而非硬编码。 \ No newline at end of file +- **配置优先**: 遇到路径、环境问题，优先检查 `.env` 或配置文件，而非硬编码。 + +--- + +## Cursor Cloud specific instructions + +This repo contains **two** independent projects (the root `README.md` has a committed merge conflict describing both): +1. **Edges pnpm workspace** — the primary product. The runnable service is the `new-note` MCP server at `extensions/mcp-servers/new-note`. See its `README.md` for tool/API details and `package.json` for the standard scripts. +2. **`claude-agent-sdk-test`** — a secondary Python starter (`src/`, `tests/`, `pyproject.toml`). + +Dependencies are pre-installed by the update script (`pnpm install` + `pip install --user -e .`); the notes below are non-obvious gotchas, not setup steps. + +### Dependency / registry gotcha (important) +- `pnpm-lock.yaml` pins tarball URLs to a **private registry** (`artifactory.devops.xiaohongshu.com`) that is **unreachable from Cursor Cloud**. A handful of packages (`cors`, `@types/cors`, `@esbuild/linux-x64`, `object-assign`) time out there. +- `node_modules` and the pnpm store are **pre-populated in the environment snapshot**, so `pnpm install` is a fast no-op (`Already up to date`) and does not touch the network. **Do not delete `node_modules`** and do not expect a clean-slate `pnpm install` to succeed online — it will hang retrying the private registry. If you ever must repopulate, fetch the missing tarballs from `https://registry.npmjs.org` (they are identical public-npm packages). + +### new-note MCP server (`extensions/mcp-servers/new-note`) +- **Run it in dev mode:** `pnpm dev:note-server` (root) or `pnpm dev` (package) → `tsx` runs `src/index.ts` in HTTP mode on `http://localhost:3000` (`/health`, MCP at `/new-note`). Dev mode uses `--env-file=.env`, so create a local (gitignored) `.env` in the package to inject vars. +- **Build output quirk:** `outDir` is defined in the root `tsconfig.base.json`, so `tsc` (via `pnpm build`) emits to **`/workspace/dist`**, not `extensions/mcp-servers/new-note/dist`. Because of this the packaged `pnpm start` (`node dist/index.js`) fails from the package dir. To run the compiled build use `node /workspace/dist/index.js --http --port 3000`, or just use dev mode (`tsx`). +- **Tests:** `pnpm test` (`node --test --import tsx`) discovers **0** tests because Node's default runner doesn't match `.ts` files. Run the suite explicitly: `node --test --import tsx test/*.test.ts` (9 tests pass). +- **Lint:** no lint tooling is configured. Root `pnpm lint` is `pnpm recursive lint`, which errors (invalid syntax); `pnpm -r run lint` reports "no lint script". There is nothing to lint. +- **Testing `new_note` safely:** the tool shells out to `bin/new-note`, which in `direct` mode commits **and pushes** to `EDGES_REPO` (defaults to the repo root) on `main`. To exercise it without mutating the real repo, point `EDGES_REPO` at a scratch git repo (that contains a copy of `bin/new-note`) and set `EDGES_DRY_RUN=true` (skips checkout/pull/push; still does a local commit). + +### Python project +- Tests: `python3 -m unittest discover -s tests` (2 tests). Running the actual CLI agent (`claude-agent-sdk-test "..."`) requires Anthropic credentials + the bundled Claude Code CLI; not needed for tests or environment verification. \ No newline at end of file