memory-journal-mcp 4.4.2 → 5.0.0

package/CONTRIBUTING.md

@@ -12,36 +12,41 @@ Thank you for your interest in contributing to the Memory Journal MCP Server! Th
 
 ## 🛠️ Development Setup
 
-### Option 1: Docker Development (Recommended)
+### Prerequisites
+
+- **Node.js 24+** (see `engines` in `package.json`)
+- **npm** (comes with Node.js)
+- **Git** (for version control and GitHub integration testing)
+- **Docker** (optional, for container testing)
+
+### Local Development
 
 ```bash
 # Clone your fork
 git clone https://github.com/YOUR_USERNAME/memory-journal-mcp.git
 cd memory-journal-mcp
 
-# Build and test with Docker
-docker build -f Dockerfile.alpine -t memory-journal-dev .
-docker run --rm -v ./data:/app/data memory-journal-dev python src/server.py
+# Install dependencies
+npm install
 
-# Test the MCP server
-docker run --rm memory-journal-dev python -c "print('✅ MCP Server ready!')"
-```
+# Build TypeScript
+npm run build
 
-### Option 2: Local Development
+# Run the test suite
+npm test
 
-```bash
-# Clone your fork
-git clone https://github.com/YOUR_USERNAME/memory-journal-mcp.git
-cd memory-journal-mcp
+# Run the full quality check
+npm run lint && npm run typecheck
+```
 
-# Install dependencies
-pip install -r requirements.txt
+### Docker Development (Optional)
 
-# Optional: Install semantic search dependencies
-pip install sentence-transformers faiss-cpu
+```bash
+# Build the Docker image locally
+docker build -f Dockerfile -t memory-journal-dev .
 
-# Test the server
-python src/server.py
+# Run with a data volume
+docker run --rm -i -v ./data:/app/data memory-journal-dev
 ```
 
 ## 📋 What We're Looking For
@@ -50,10 +55,10 @@ We especially welcome contributions in these areas:
 
 ### 🎯 High Priority
 
-- **New entry types** that make sense for developer workflows
-- **Better Git/GitHub integrations** (more context, better performance)
-- **Performance improvements** (faster search, reduced memory usage)
 - **Bug fixes** and stability improvements
+- **Performance improvements** (faster search, reduced memory usage)
+- **Better Git/GitHub integrations** (more context, better performance)
+- **New entry types** that make sense for developer workflows
 
 ### 🔍 Medium Priority
 
@@ -64,31 +69,49 @@ We especially welcome contributions in these areas:
 
 ### 💡 Future Features
 
-- **Graph visualization** of entry relationships
+- **Graph visualization** enhancements for entry relationships
 - **Weekly/monthly auto-summaries**
-- **Team collaboration** features
+- **Team collaboration** improvements
 - **IDE integrations** beyond MCP
 
 ## 🧪 Testing Your Changes
 
-### Manual Testing
+### Automated Testing
 
 ```bash
-# Test basic functionality
-python -c "
-import sys
-sys.path.append('src')
-from server import *
-print('✅ Server imports successfully')
-"
-
-# Test with MCP client (Cursor)
-# Add your local server to ~/.cursor/mcp.json:
+# Run all tests
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Run tests with coverage
+npm run test:coverage
+
+# Run benchmarks
+npm run bench
+```
+
+### Quality Checks
+
+```bash
+# Lint + type check (required before submitting)
+npm run lint && npm run typecheck
+
+# Format code with Prettier
+npx prettier --write .
+```
+
+### Manual Testing with MCP Client
+
+Add your local build to `~/.cursor/mcp.json`:
+
+```json
 {
   "mcpServers": {
     "memory-journal-dev": {
-      "command": "python",
-      "args": ["path/to/your/memory-journal-mcp/src/server.py"]
+      "command": "node",
+      "args": ["path/to/your/memory-journal-mcp/dist/cli.js"]
     }
   }
 }
@@ -96,40 +119,42 @@ print('✅ Server imports successfully')
 
 ### Docker Testing
 
-````bash
-# Test alpine build
-docker build -f Dockerfile.alpine -t test-alpine .
-docker run --rm test-alpine python -c "print('Alpine build works!')"
+```bash
+# Build and run locally
+docker build -f Dockerfile -t memory-journal-dev .
+docker run --rm -i -v ./data:/app/data memory-journal-dev
+```
 
-# Test full build
-docker build -f Dockerfile -t test-full .
-docker run --rm test-full python -c "print('Full build works!')"
-```## 📝 Coding Standards
+## 📝 Coding Standards
 
-### Python Code Style
-- **PEP 8 compliance** - Use `black` for formatting
-- **Type hints** - Add type annotations for new functions
-- **Docstrings** - Document public functions and classes
-- **Async/await** - Use async patterns for I/O operations
-- **Error handling** - Implement graceful fallbacks
+### TypeScript Code Style
+
+- **Strict mode** — `tsconfig.json` enforces strict TypeScript
+- **ESLint** — Run `npm run lint` to check, `npm run lint:fix` to auto-fix
+- **Prettier** — Run `npx prettier --write .` for formatting
+- **Type safety** — Avoid `any`; use proper types and Zod schemas
+- **Modularity** — Keep files under ~500 lines; split into sub-modules when approaching the limit
+- **Error handling** — Use `formatHandlerError()` for structured `{success, error}` responses in tool handlers
 
 ### Database Changes
-- **Schema migrations** - Update `src/schema.sql` for database changes
-- **Backward compatibility** - Ensure existing data isn't broken
-- **Performance** - Consider index implications for new queries
-- **Testing** - Verify with both empty and populated databases
+
+- **Schema migrations** — Update `src/database/schema.ts` for database changes
+- **Backward compatibility** — Ensure existing data isn't broken; use `migrateSchema()` for column additions
+- **Performance** — Consider index implications for new queries
+- **Testing** — Verify with both empty and populated databases
 
 ### Docker Considerations
-- **Multi-stage builds** - Keep images lean
-- **Security** - Run as non-root user, minimal privileges
-- **Compatibility** - Test on both lite and full variants
-- **Documentation** - Update Docker guides if needed
+
+- **Multi-stage builds** — Keep images lean
+- **Security** — Run as non-root user, minimal privileges
+- **Multi-platform** — Test on both amd64 and arm64 when possible
+- **Documentation** — Update Docker guides if needed
 
 ## 🐛 Bug Reports
 
 When reporting bugs, please include:
 
-1. **Environment details** (OS, Python version, Docker version)
+1. **Environment details** (OS, Node.js version, npm version)
 2. **Steps to reproduce** the issue
 3. **Expected vs actual behavior**
 4. **MCP client details** (Cursor version, configuration)
@@ -142,76 +167,86 @@ Use our [Bug Report template](.github/ISSUE_TEMPLATE/bug_report.md) for consiste
 
 For new features, please provide:
 
-1. **Use case description** - What problem does this solve?
-2. **Proposed solution** - How should it work?
-3. **Developer workflow** - How does this fit into dev work?
-4. **Alternatives considered** - What other approaches did you think about?
-5. **Implementation notes** - Any technical considerations
+1. **Use case description** — What problem does this solve?
+2. **Proposed solution** — How should it work?
+3. **Developer workflow** — How does this fit into dev work?
+4. **Alternatives considered** — What other approaches did you think about?
+5. **Implementation notes** — Any technical considerations
 
 Use our [Feature Request template](.github/ISSUE_TEMPLATE/feature_request.md).
 
 ## 🔄 Pull Request Process
 
 ### Before Submitting
+
 - [ ] **Fork** the repository and create a feature branch
-- [ ] **Test** your changes thoroughly (manual + Docker)
+- [ ] **Test** your changes (`npm test`, `npm run lint && npm run typecheck`)
+- [ ] **Format** your code (`npx prettier --write .`)
 - [ ] **Update documentation** if you changed APIs or behavior
 - [ ] **Add examples** for new features
 - [ ] **Check** that existing functionality still works
 
 ### PR Description Should Include
+
 - **Summary** of changes made
 - **Testing** performed (how did you verify it works?)
 - **Breaking changes** (if any)
 - **Related issues** (fixes #123)
-- **Screenshots** (for UI changes)
 
 ### Review Process
-1. **Automated checks** must pass
-2. **Maintainer review** - we'll provide feedback
-3. **Address feedback** - make requested changes
-4. **Merge** - once approved, we'll merge your PR
+
+1. **Automated checks** must pass (lint, typecheck, tests)
+2. **Maintainer review** — we'll provide feedback
+3. **Address feedback** — make requested changes
+4. **Merge** — once approved, we'll merge your PR
 
 ## 🎯 Development Tips
 
 ### Working with MCP
-- **Test in Cursor** - The primary MCP client environment
-- **Check tool responses** - Ensure JSON responses are well-formed
-- **Handle timeouts** - Git operations should fail fast
-- **Async safety** - All blocking operations in thread pools
-
-### Database Development
-- **Use WAL mode** - Already configured for concurrency
-- **FTS5 integration** - Full-text search is performance-critical
-- **Proper transactions** - Always commit changes
-- **Index optimization** - Consider query performance
-
-### Docker Development
-```bash
-# Quick rebuild and test cycle
-docker build -f Dockerfile.alpine -t dev-test . && \
-docker run --rm -v ./data:/app/data dev-test python src/server.py
-````
+
+- **Test in Cursor** — The primary MCP client environment
+- **Check tool responses** — Ensure JSON responses are well-formed
+- **Output schemas** — All tools have Zod output schemas; error responses must pass validation
+- **Dual-schema pattern** — Relaxed schemas for SDK validation, strict schemas inside handlers
+
+### Architecture Overview
+
+```
+src/
+├── cli.ts                  # CLI entry point (Commander)
+├── McpServer.ts            # MCP server setup (tools, resources, prompts)
+├── database/
+│   ├── SqliteAdapter.ts    # SQLite operations via sql.js
+│   └── schema.ts           # DDL + input types
+├── handlers/
+│   ├── tools/              # 42 tool handlers (9 groups)
+│   ├── resources/          # 22 resource handlers
+│   └── prompts/            # 15 prompt handlers
+├── transports/
+│   └── http.ts             # HTTP/SSE transport layer
+├── types/                  # TypeScript type definitions
+└── utils/                  # Shared utilities
+```
 
 ## 🤝 Community
 
-- **Be respectful** - Follow our [Code of Conduct](CODE_OF_CONDUCT.md)
-- **Ask questions** - Use GitHub Discussions for help
-- **Share ideas** - Feature requests and feedback welcome
-- **Help others** - Answer questions and review PRs
+- **Be respectful** — Follow our [Code of Conduct](CODE_OF_CONDUCT.md)
+- **Ask questions** — Use GitHub Discussions for help
+- **Share ideas** — Feature requests and feedback welcome
+- **Help others** — Answer questions and review PRs
 
 ## 📞 Getting Help
 
-- **GitHub Issues** - Bug reports and feature requests
-- **GitHub Discussions** - Questions and community chat
-- **Documentation** - Check README.md and Docker guides first
+- **GitHub Issues** — Bug reports and feature requests
+- **GitHub Discussions** — Questions and community chat
+- **Documentation** — Check [README.md](README.md), [Wiki](https://github.com/neverinfamous/memory-journal-mcp/wiki), and Docker guides first
 
 ## 🏆 Recognition
 
 Contributors are recognized in:
 
-- **Release notes** - Major contributions highlighted
-- **README** - Contributor acknowledgments
-- **Git history** - Your commits are permanent record
+- **Release notes** — Major contributions highlighted
+- **README** — Contributor acknowledgments
+- **Git history** — Your commits are permanent record
 
 Thank you for helping make Memory Journal MCP Server better for the developer community! 🚀