This project follows security best practices for MCP servers and API token management:

Never commit sensitive information to git:

• ✅ .env - Contains API tokens and database IDs (excluded from git)
• ✅ .env.local - Local environment overrides (excluded from git)
• ✅ .env.backup - Backup credentials (excluded from git)
• ✅ claude_desktop_config.json - Contains credentials (user-managed)

Safe to commit:

• ✅ .env.example - Template with placeholders
• ✅ Source code without credentials
• ✅ Test files with mock data
• ✅ Configuration templates
• ✅ Documentation files

This repository provides example configuration files:

1. .env.example - Template for environment variables

   • Copy to .env
   • Replace placeholders with your actual values
   • Never commit the actual .env file

2. Claude Desktop Config - MCP server configuration

   • Edit via Claude Desktop settings
   • Stores credentials in claude_desktop_config.json
   • Managed by Claude Desktop (not in this repository)

Included in repository:

• Source code (.ts files)
• Tests (*.test.ts files)
• Compiled JavaScript (dist/ folder for npm package)
• Documentation (.md files)
• Configuration templates (.example files)
• GitHub Actions workflows
• Build configuration (tsconfig.json, package.json)

Excluded from repository (.gitignore):

• .env* - Environment variables and secrets
• node_modules/ - Dependencies
• coverage/ - Test coverage reports
• Temporary files and IDE configs

When contributing:

1. Never commit credentials - Use .env file (excluded from git)
2. Use example files - Provide templates, not actual configs
3. Review before push - Run git diff to check for sensitive data
4. Use .gitignore - Ensure secrets are excluded
5. Rotate exposed secrets - If accidentally committed, rotate immediately

Cloudflare API Token Management:

• API tokens grant full access to your Cloudflare account
• Treat API tokens like passwords - never share or commit them
• Use scoped tokens with minimum required permissions:
  • D1 Read access (for schema introspection)
  • Limit to specific account ID
• Rotate tokens regularly (every 90 days recommended)
• Revoke tokens immediately if compromised

Database ID Security:

• Database IDs are not highly sensitive but should be kept private
• They cannot be used without a valid API token
• Separate databases for development, staging, and production
• Never expose production database IDs in examples

Model Context Protocol (MCP):

• MCP servers run locally and communicate via stdio
• Credentials stored in Claude Desktop config (user's local machine)
• No network exposure by default
• All API calls originate from local machine

Security Boundaries:

• MCP server → Cloudflare D1 REST API (HTTPS only)
• Environment isolation (dev/staging/prod databases)
• Read-only schema introspection (no data modification)
• Caching layer prevents excessive API calls

If you discover a security vulnerability:

1. Do NOT open a public issue
2. Email: [email protected]
3. Include:
   • Description of the vulnerability
   • Steps to reproduce
   • Potential impact
   • Suggested fix (if any)

We will respond within 48 hours and work with you to address the issue.

This project implements:

• ✅ TypeScript Strict Mode - Type safety prevents runtime errors
• ✅ Input Validation - Domain entities validate all inputs
• ✅ Error Handling - Graceful degradation without leaking sensitive info
• ✅ Dependency Audits - npm audit in CI/CD pipeline
• ✅ Automated Testing - 398 tests prevent security regressions
• ✅ Immutable Entities - Object.freeze() prevents mutation
• ✅ Environment Isolation - Separate dev/staging/prod configurations
• ✅ Cache TTL - 10-minute expiration prevents stale data attacks
• ✅ HTTPS-Only - All Cloudflare API calls use HTTPS

Before deploying to production:

• .env file is in .gitignore ✅ (already configured)
• API tokens are not in git history
• No .env or credential files committed
• All tests passing (npm test)
• No npm audit vulnerabilities (check with npm audit)
• Secrets rotated if ever exposed
• Production database access restricted
• Claude Desktop config uses production credentials only in production
• Verify .npmignore excludes source files and tests

1. Go to Cloudflare Dashboard
2. Navigate to My Profile → API Tokens
3. Click Create Token
4. Use Custom Token template
5. Set permissions:
   • Account → D1 → Read
6. Set account restriction to your account ID
7. Save token securely (shown only once!)

Rotate API tokens every 90 days:

1. Create new token with same permissions
2. Update .env file with new token
3. Test MCP server functionality
4. Revoke old token in Cloudflare Dashboard

If your API token is compromised:

1. Immediately revoke the token in Cloudflare Dashboard
2. Create a new token with different permissions if possible
3. Update .env file and Claude Desktop config
4. Review Cloudflare audit logs for unauthorized access
5. Report the incident to [email protected]

• Weekly: Check for dependency updates
• Monthly: Update dependencies (npm update)
• Monthly: Run security audits (npm audit)
• Quarterly: Rotate API tokens
• Quarterly: Review and update access controls

✅ Safe to Share Publicly:

• This repository (source code, tests, documentation)
• Build artifacts (dist/ folder)
• npm package (@semanticintent/semantic-d1-mcp)
• Database schema structure (no data)
• Sample queries and examples

❌ Never Share Publicly:

• Cloudflare API tokens
• Database IDs (especially production)
• Environment variable files (.env)
• Claude Desktop config with credentials
• Actual database data
• Logs containing credentials

• Email: [email protected]
• Response Time: Within 48 hours
• GPG Key: Available upon request

Last Updated: 2025-10-07 Security Contact: [email protected]