agentleFS
dominik1001dominik1001/caldav-mcp/AGENTS.md

caldav-mcp

AGENTS.md112 starsChanged 25 days agoMITView on GitHub

MCP server exposing CalDAV calendar operations as tools for AI assistants. .mcp.json at the repo root registers the server (loads .env via node --env-file) so both the agent smoke and interactive Claude Code sessions pick it up automatically. Cost and side effects (locally, .env points at a real account): - Needs: .env with CALDAV_BASE_URL, CALDAV_USERNAME, CALDAV_PASSWORD. smoke:agent also needs claude and jq on PATH. Both scripts run npm run build first. - smoke writes real data to the first calendar…

  • Reads credentials
  • Installs packages
  • Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.

    Of the AGENTS.md files we read, the 33,315 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

  • In this repository3 other files it gives its agents.

The file

Show its rules and text

We split this AGENTS.md into the rules it gives an agent

53 rules. About 0 are common, 28 are distinctive, and 25 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈28

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 25

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    After implementing a new feature run the smoke tests (npm run smoke and npm run smoke:agent) to verify it works as expected.

    line 18
  2. Distinctive:

    When the user asks a question, answer it before editing files or running implementation commands.

    line 21
  3. Distinctive:

    When responding to feedback or a review, say whether you agree or disagree before saying what you changed.

    line 22
  4. Very specific:

    Treat package.json and package-lock.json changes as reviewed code.

    line 26
  5. Very specific:

    Ask before adding a dep that has lifecycle scripts (preinstall, install, postinstall).

    line 29
  6. Distinctive:

    Write code that is accessible, performant, type-safe, and maintainable.

    line 62
  7. Distinctive:

    Use explicit types for function parameters and return values when they enhance clarity

    line 66
  8. Very specific:

    Prefer unknown over any when the type is genuinely unknown

    line 67
  9. Very specific:

    Use const assertions (as const) for immutable values and literal types

    line 68
  10. Distinctive:

    Use meaningful variable names instead of magic numbers - extract constants with descriptive names

    line 70
  11. Distinctive:

    Use arrow functions for callbacks and short functions

    line 74
  12. Very specific:

    Prefer for...of loops over .forEach() and indexed for loops

    line 75
  13. Very specific:

    Use optional chaining (?.) and nullish coalescing (??) for safer property access

    line 76
  14. Distinctive:

    Prefer template literals over string concatenation

    line 77
  15. Distinctive:

    Use destructuring for object and array assignments

    line 78
  16. Very specific:

    Use const by default, let only when reassignment is needed, never var

    line 79
  17. Very specific:

    Always await promises in async functions - don't forget to use the return value

    line 83
  18. Very specific:

    Use async/await syntax instead of promise chains for better readability

    line 84
  19. Distinctive:

    Don't use async functions as Promise executors

    line 86
  20. Distinctive:

    Use function components over class components

    line 90
  21. Distinctive:

    Call hooks at the top level only, never conditionally

    line 91
  22. Very specific:

    Use the key prop for elements in iterables (prefer unique IDs over array indices)

    line 93
  23. Distinctive:

    Don't define components inside other components

    line 95
  24. Distinctive:

    Use semantic HTML and ARIA attributes for accessibility:

    line 96
  25. Distinctive:

    Use proper heading hierarchy

    line 98
  26. Distinctive:

    Add labels for form inputs

    line 99
  27. Very specific:

    Use semantic elements (<button>, <nav>, etc.) instead of divs with roles

    line 101
  28. Very specific:

    Remove console.log, debugger, and alert statements from production code

    line 105
  29. Very specific:

    Use try-catch blocks meaningfully - don't catch errors just to rethrow them

    line 107
  30. Distinctive:

    Prefer early returns over nested conditionals for error cases

    line 108
  31. Distinctive:

    Keep functions focused and under reasonable cognitive complexity limits

    line 112
  32. Distinctive:

    Use early returns to reduce nesting

    line 114
  33. Distinctive:

    Prefer simple conditionals over nested ternary operators

    line 115
  34. Distinctive:

    Avoid import cycles; move shared code into a module both sides import

    line 117
  35. Very specific:

    Add rel="noopener noreferrer" when using target="_blank" on links

    line 121
  36. Very specific:

    Avoid dangerouslySetInnerHTML unless absolutely necessary

    line 122
  37. Very specific:

    Don't use eval() or assign directly to document.cookie

    line 123
  38. Distinctive:

    Avoid spread syntax in accumulators within loops

    line 128
  39. Distinctive:

    Use top-level regex literals instead of creating them in loops

    line 129
  40. Distinctive:

    Prefer specific imports over namespace imports

    line 130
  41. Distinctive:

    Avoid barrel files (index files that re-export everything)

    line 131
  42. Very specific:

    Use proper image components (e.g., Next.js <Image>) over <img> tags

    line 132
  43. Very specific:

    Use Next.js <Image> component for images

    line 137
  44. Very specific:

    Use next/head or App Router metadata API for head elements

    line 138
  45. Distinctive:

    Use Server Components for async data fetching instead of async Client Components

    line 139
  46. Very specific:

    Use ref as a prop instead of React.forwardRef

    line 142
  47. Very specific:

    Use class and for attributes (not className or htmlFor)

    line 145
  48. Very specific:

    Write assertions inside it() or test() blocks

    line 151
  49. Distinctive:

    Avoid done callbacks in async tests - use async/await instead

    line 152
  50. Very specific:

    Don't use .only or .skip in committed code

    line 153
  51. Very specific:

    Keep test suites reasonably flat - avoid excessive describe nesting

    line 154
  52. Distinctive:

    Meaningful naming: - Use descriptive names for functions, variables, and types

    line 161
  53. Distinctive:

    Documentation: - Add comments for complex logic, but prefer self-documenting code

    line 165

≈ “Common” is an estimate: at least 1 in 5 of the 42,283 AGENTS.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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

caldav-mcp

MCP server exposing CalDAV calendar operations as tools for AI assistants.

Tech Stack

  • TypeScript, ESM ("type": "module"), Node ≥18, compiled with tsc to dist/.
  • Biome for lint + format (npm run check / check:fix) — do not add ESLint or Prettier.
  • Vitest for tests, lefthook for git hooks, semantic-release for publishing.
  • Runtime deps: @modelcontextprotocol/sdk, ts-caldav, zod.

Layout

  • src/index.ts — server entry; wires up StdioServerTransport and registers tools.
  • src/tools/<tool>.ts — one file per MCP tool, with *.test.ts next to it.
  • Credentials come from .env (see .env.example); dev loads it via tsx --env-file=.env, not dotenv.

Workflow

  • Dev: npm run dev (watch). Build: npm run build. Test: npm test.
  • After implementing a new feature run the smoke tests (npm run smoke and npm run smoke:agent) to verify it works as expected. See "Smoke tests" for what they cost and when to skip them.

Working with the user

  • When the user asks a question, answer it before editing files or running implementation commands.
  • When responding to feedback or a review, say whether you agree or disagree before saying what you changed.
  • Explain non-trivial designs or bugs as problem → concrete example or short trace → solution, and say why any added complexity is needed.

Dependencies

  • Treat package.json and package-lock.json changes as reviewed code; say why a dep is added or bumped.
  • .npmrc pins new deps to exact versions (save-exact) and ignores versions published less than 2 days ago (min-release-age). Don't rewrite existing ^ ranges.
  • min-release-age only applies when npm resolves a version (npm install <pkg>, npm update). npm ci installs the lockfile as is.
  • Ask before adding a dep that has lifecycle scripts (preinstall, install, postinstall).
  • Install locally with scripts on: prepare runs lefthook install, so --ignore-scripts skips the git hooks. npm ci --ignore-scripts fits CI jobs that only need node_modules.

Smoke tests

Two complementary end-to-end checks against a real CalDAV server (uses .env):

  • npm run smoke — deterministic SDK harness (scripts/smoke.ts). Spawns the built server over stdio via the MCP client SDK and asserts the create → list → update → delete round-trip. Fast, no LLM cost. CI runs it on every PR and push to main against a throwaway Radicale server (smoke job in release.yml).
  • npm run smoke:agent — agent-ergonomics harness (scripts/smoke-agent.sh). Drives the server via claude -p with a JSON output schema, validating that tool names, descriptions, schemas, and error messages are usable by an LLM.

.mcp.json at the repo root registers the server (loads .env via node --env-file) so both the agent smoke and interactive Claude Code sessions pick it up automatically.

Cost and side effects (locally, .env points at a real account):

  • Needs: .env with CALDAV_BASE_URL, CALDAV_USERNAME, CALDAV_PASSWORD. smoke:agent also needs claude and jq on PATH. Both scripts run npm run build first.
  • smoke writes real data to the first calendar list-calendars returns: two events 1h from now (one addressed by absolute URL, one by server-relative path), a daily ×3 recurring event 2h from now, a whole-day event on 2030-08-18, and a yearly whole-day event 3 days from now (ending four years on). If a calendar supports VTODO, it also creates, completes, updates, and deletes a todo on the first such calendar. Everything is deleted on success.
  • smoke cleans up on failure only for the relative-path event and the two whole-day events (try/finally). Any other failure, or a killed run, can leave events or the todo behind; their summaries start with caldav-mcp smoke.
  • smoke:agent runs a full claude -p session: costs LLM tokens on your Claude account, uses your default model, and is slower than smoke. The model creates, renames, lists, and deletes a test event 1h from now on the first calendar, then calls list-events with an invalid date. Cleanup depends on the model following the prompt; the script itself deletes nothing, so an aborted run can leave an event with a model-chosen title.
  • Skip both for docs-only, test-only, or CI/tooling changes that don't touch src/. For other src/ changes, smoke is usually enough; run smoke:agent too when tool names, descriptions, schemas, or error messages change.

Ultracite Code Standards

This project uses Ultracite, a zero-config preset that enforces strict code quality standards through automated formatting and linting.

Quick Reference

  • Format code: npx ultracite fix
  • Check for issues: npx ultracite check
  • Diagnose setup: npx ultracite doctor

Biome (the underlying engine) provides robust linting and formatting. Most issues are automatically fixable.


Core Principles

Write code that is accessible, performant, type-safe, and maintainable. Focus on clarity and explicit intent over brevity.

Type Safety & Explicitness

  • Use explicit types for function parameters and return values when they enhance clarity
  • Prefer unknown over any when the type is genuinely unknown
  • Use const assertions (as const) for immutable values and literal types
  • Leverage TypeScript's type narrowing instead of type assertions
  • Use meaningful variable names instead of magic numbers - extract constants with descriptive names

Modern JavaScript/TypeScript

  • Use arrow functions for callbacks and short functions
  • Prefer for...of loops over .forEach() and indexed for loops
  • Use optional chaining (?.) and nullish coalescing (??) for safer property access
  • Prefer template literals over string concatenation
  • Use destructuring for object and array assignments
  • Use const by default, let only when reassignment is needed, never var

Async & Promises

  • Always await promises in async functions - don't forget to use the return value
  • Use async/await syntax instead of promise chains for better readability
  • Handle errors appropriately in async code with try-catch blocks
  • Don't use async functions as Promise executors

React & JSX

  • Use function components over class components
  • Call hooks at the top level only, never conditionally
  • Specify all dependencies in hook dependency arrays correctly
  • Use the key prop for elements in iterables (prefer unique IDs over array indices)
  • Nest children between opening and closing tags instead of passing as props
  • Don't define components inside other components
  • Use semantic HTML and ARIA attributes for accessibility:
    • Provide meaningful alt text for images
    • Use proper heading hierarchy
    • Add labels for form inputs
    • Include keyboard event handlers alongside mouse events
    • Use semantic elements (<button>, <nav>, etc.) instead of divs with roles

Error Handling & Debugging

  • Remove console.log, debugger, and alert statements from production code
  • Throw Error objects with descriptive messages, not strings or other values
  • Use try-catch blocks meaningfully - don't catch errors just to rethrow them
  • Prefer early returns over nested conditionals for error cases

Code Organization

  • Keep functions focused and under reasonable cognitive complexity limits
  • Extract complex conditions into well-named boolean variables
  • Use early returns to reduce nesting
  • Prefer simple conditionals over nested ternary operators
  • Group related code together and separate concerns
  • Avoid import cycles; move shared code into a module both sides import

Security

  • Add rel="noopener noreferrer" when using target="_blank" on links
  • Avoid dangerouslySetInnerHTML unless absolutely necessary
  • Don't use eval() or assign directly to document.cookie
  • Validate and sanitize user input

Performance

  • Avoid spread syntax in accumulators within loops
  • Use top-level regex literals instead of creating them in loops
  • Prefer specific imports over namespace imports
  • Avoid barrel files (index files that re-export everything)
  • Use proper image components (e.g., Next.js <Image>) over <img> tags

Framework-Specific Guidance

Next.js:

  • Use Next.js <Image> component for images
  • Use next/head or App Router metadata API for head elements
  • Use Server Components for async data fetching instead of async Client Components

React 19+:

  • Use ref as a prop instead of React.forwardRef

Solid/Svelte/Vue/Qwik:

  • Use class and for attributes (not className or htmlFor)

Testing

  • Write assertions inside it() or test() blocks
  • Avoid done callbacks in async tests - use async/await instead
  • Don't use .only or .skip in committed code
  • Keep test suites reasonably flat - avoid excessive describe nesting

When Biome Can't Help

Biome will catch most mechanical issues automatically. Focus your attention on:

  1. Business logic correctness - Biome can't validate your algorithms
  2. Meaningful naming - Use descriptive names for functions, variables, and types
  3. Architecture decisions - Component structure, data flow, and API design
  4. Edge cases - Handle boundary conditions and error states
  5. User experience - Accessibility, performance, and usability considerations
  6. Documentation - Add comments for complex logic, but prefer self-documenting code

Most formatting and common issues are automatically fixed by Biome. Run npx ultracite fix before committing to ensure compliance.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.