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.
- scion-like-gitSkill
- ultraciteSkill
- triage-issueSkill
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
- Very specific: line 18
After implementing a new feature run the smoke tests (npm run smoke and npm run smoke:agent) to verify it works as expected.
- Distinctive: line 21
When the user asks a question, answer it before editing files or running implementation commands.
- Distinctive: line 22
When responding to feedback or a review, say whether you agree or disagree before saying what you changed.
- Very specific: line 26
Treat package.json and package-lock.json changes as reviewed code.
- Very specific: line 29
Ask before adding a dep that has lifecycle scripts (preinstall, install, postinstall).
- Distinctive: line 62
Write code that is accessible, performant, type-safe, and maintainable.
- Distinctive: line 66
Use explicit types for function parameters and return values when they enhance clarity
- Very specific: line 67
Prefer unknown over any when the type is genuinely unknown
- Very specific: line 68
Use const assertions (as const) for immutable values and literal types
- Distinctive: line 70
Use meaningful variable names instead of magic numbers - extract constants with descriptive names
- Distinctive: line 74
Use arrow functions for callbacks and short functions
- Very specific: line 75
Prefer for...of loops over .forEach() and indexed for loops
- Very specific: line 76
Use optional chaining (?.) and nullish coalescing (??) for safer property access
- Distinctive: line 77
Prefer template literals over string concatenation
- Distinctive: line 78
Use destructuring for object and array assignments
- Very specific: line 79
Use const by default, let only when reassignment is needed, never var
- Very specific: line 83
Always await promises in async functions - don't forget to use the return value
- Very specific: line 84
Use async/await syntax instead of promise chains for better readability
- Distinctive: line 86
Don't use async functions as Promise executors
- Distinctive: line 90
Use function components over class components
- Distinctive: line 91
Call hooks at the top level only, never conditionally
- Very specific: line 93
Use the key prop for elements in iterables (prefer unique IDs over array indices)
- Distinctive: line 95
Don't define components inside other components
- Distinctive: line 96
Use semantic HTML and ARIA attributes for accessibility:
- Distinctive: line 98
Use proper heading hierarchy
- Distinctive: line 99
Add labels for form inputs
- Very specific: line 101
Use semantic elements (<button>, <nav>, etc.) instead of divs with roles
- Very specific: line 105
Remove console.log, debugger, and alert statements from production code
- Very specific: line 107
Use try-catch blocks meaningfully - don't catch errors just to rethrow them
- Distinctive: line 108
Prefer early returns over nested conditionals for error cases
- Distinctive: line 112
Keep functions focused and under reasonable cognitive complexity limits
- Distinctive: line 114
Use early returns to reduce nesting
- Distinctive: line 115
Prefer simple conditionals over nested ternary operators
- Distinctive: line 117
Avoid import cycles; move shared code into a module both sides import
- Very specific: line 121
Add rel="noopener noreferrer" when using target="_blank" on links
- Very specific: line 122
Avoid dangerouslySetInnerHTML unless absolutely necessary
- Very specific: line 123
Don't use eval() or assign directly to document.cookie
- Distinctive: line 128
Avoid spread syntax in accumulators within loops
- Distinctive: line 129
Use top-level regex literals instead of creating them in loops
- Distinctive: line 130
Prefer specific imports over namespace imports
- Distinctive: line 131
Avoid barrel files (index files that re-export everything)
- Very specific: line 132
Use proper image components (e.g., Next.js <Image>) over <img> tags
- Very specific: line 137
Use Next.js <Image> component for images
- Very specific: line 138
Use next/head or App Router metadata API for head elements
- Distinctive: line 139
Use Server Components for async data fetching instead of async Client Components
- Very specific: line 142
Use ref as a prop instead of React.forwardRef
- Very specific: line 145
Use class and for attributes (not className or htmlFor)
- Very specific: line 151
Write assertions inside it() or test() blocks
- Distinctive: line 152
Avoid done callbacks in async tests - use async/await instead
- Very specific: line 153
Don't use .only or .skip in committed code
- Very specific: line 154
Keep test suites reasonably flat - avoid excessive describe nesting
- Distinctive: line 161
Meaningful naming: - Use descriptive names for functions, variables, and types
- Distinctive: line 165
Documentation: - Add comments for complex logic, but prefer self-documenting code
≈ “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.
Files
caldav-mcp
MCP server exposing CalDAV calendar operations as tools for AI assistants.
Tech Stack
- TypeScript, ESM (
"type": "module"), Node ≥18, compiled withtsctodist/. - 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 upStdioServerTransportand registers tools.src/tools/<tool>.ts— one file per MCP tool, with*.test.tsnext to it.- Credentials come from
.env(see.env.example); dev loads it viatsx --env-file=.env, notdotenv.
Workflow
- Dev:
npm run dev(watch). Build:npm run build. Test:npm test. - After implementing a new feature run the smoke tests (
npm run smokeandnpm 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.jsonandpackage-lock.jsonchanges as reviewed code; say why a dep is added or bumped. .npmrcpins 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-ageonly applies when npm resolves a version (npm install <pkg>,npm update).npm ciinstalls the lockfile as is.- Ask before adding a dep that has lifecycle scripts (
preinstall,install,postinstall). - Install locally with scripts on:
preparerunslefthook install, so--ignore-scriptsskips the git hooks.npm ci --ignore-scriptsfits CI jobs that only neednode_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 tomainagainst a throwaway Radicale server (smokejob inrelease.yml).npm run smoke:agent— agent-ergonomics harness (scripts/smoke-agent.sh). Drives the server viaclaude -pwith 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:
.envwithCALDAV_BASE_URL,CALDAV_USERNAME,CALDAV_PASSWORD.smoke:agentalso needsclaudeandjqon PATH. Both scripts runnpm run buildfirst. smokewrites real data to the first calendarlist-calendarsreturns: 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.smokecleans 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 withcaldav-mcp smoke.smoke:agentruns a fullclaude -psession: costs LLM tokens on your Claude account, uses your default model, and is slower thansmoke. The model creates, renames, lists, and deletes a test event 1h from now on the first calendar, then callslist-eventswith 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 othersrc/changes,smokeis usually enough; runsmoke:agenttoo 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
unknownoveranywhen 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...ofloops over.forEach()and indexedforloops - Use optional chaining (
?.) and nullish coalescing (??) for safer property access - Prefer template literals over string concatenation
- Use destructuring for object and array assignments
- Use
constby default,letonly when reassignment is needed, nevervar
Async & Promises
- Always
awaitpromises in async functions - don't forget to use the return value - Use
async/awaitsyntax 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
keyprop 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, andalertstatements from production code - Throw
Errorobjects with descriptive messages, not strings or other values - Use
try-catchblocks 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 usingtarget="_blank"on links - Avoid
dangerouslySetInnerHTMLunless absolutely necessary - Don't use
eval()or assign directly todocument.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/heador 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
classandforattributes (notclassNameorhtmlFor)
Testing
- Write assertions inside
it()ortest()blocks - Avoid done callbacks in async tests - use async/await instead
- Don't use
.onlyor.skipin committed code - Keep test suites reasonably flat - avoid excessive
describenesting
When Biome Can't Help
Biome will catch most mechanical issues automatically. Focus your attention on:
- Business logic correctness - Biome can't validate your algorithms
- Meaningful naming - Use descriptive names for functions, variables, and types
- Architecture decisions - Component structure, data flow, and API design
- Edge cases - Handle boundary conditions and error states
- User experience - Accessibility, performance, and usability considerations
- 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.
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
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.

