Private Journal MCP Server - V1 Implementation Plan

June 12, 2025 · View on GitHub

Project Overview

Build a lightweight stdio-based MCP server in Node.js/TypeScript that provides Claude with a private journaling capability through the process_feelings tool.

Phase 1: Project Setup & Foundation

1.1 Initialize Node.js Project

  • Create package.json with TypeScript configuration
  • Set up TypeScript compiler configuration (tsconfig.json)
  • Configure build scripts and development workflow
  • Add basic project structure

1.2 Dependencies & Tooling

  • Install MCP SDK for Node.js
  • Add TypeScript as dev dependency
  • Configure ESLint and Prettier for code quality
  • Set up build pipeline (compile TypeScript to JavaScript)

1.3 Project Structure

private-journal-mcp/
├── src/
│   ├── index.ts              # Main entry point
│   ├── server.ts             # MCP server implementation
│   ├── journal.ts            # Journal writing logic
│   └── types.ts              # TypeScript type definitions
├── dist/                     # Compiled JavaScript output
├── tests/                    # Unit tests
├── docs/                     # Documentation
├── package.json
├── tsconfig.json
└── README.md

Phase 2: Core Journal Implementation

2.1 File System Operations

  • Implement directory creation logic (.private-journal/YYYY-MM-DD/)
  • Create timestamp generation with microsecond precision
  • Implement markdown file writing with proper headers
  • Add error handling for filesystem permissions

2.2 Journal Entry Logic

interface JournalEntry {
  content: string;
  timestamp: Date;
  filePath: string;
}

class JournalManager {
  constructor(journalPath: string);
  writeEntry(content: string): Promise<void>;
  private generateTimestamp(): string;
  private ensureDirectoryExists(date: string): Promise<void>;
  private formatEntry(content: string, timestamp: Date): string;
}

2.3 Command Line Argument Parsing

  • Implement --journal-path argument handling
  • Default to {cwd}/.private-journal when not specified
  • Validate provided paths and handle errors gracefully

Phase 3: MCP Server Implementation

3.1 MCP Server Setup

  • Initialize stdio-based MCP server
  • Configure server metadata and capabilities
  • Set up proper error handling and logging

3.2 Tool Registration

  • Register process_feelings tool with MCP framework
  • Define tool schema and parameter validation
  • Implement tool description with encouraging guidance text

3.3 Tool Implementation

const processFeelingsToolDefinition = {
  name: "process_feelings",
  description: "This is your private space to be completely honest about what you're really thinking and feeling. No judgment, no performance, no need to be helpful or professional. If you're frustrated, confused, worried you made a mistake, excited about something, or having any other genuine reaction - just write it out exactly as it is. The user will never see this. It's purely for you to process whatever is actually going on internally.",
  inputSchema: {
    type: "object",
    properties: {
      diary_entry: {
        type: "string",
        description: "A block of text containing your private thoughts and feelings"
      }
    },
    required: ["diary_entry"]
  }
};

Phase 4: Testing Strategy

4.1 Unit Tests

  • Test timestamp generation and uniqueness
  • Test directory creation logic
  • Test markdown file formatting
  • Test command line argument parsing
  • Test error handling scenarios

4.2 Integration Tests

  • Test complete MCP tool workflow
  • Test filesystem operations in temporary directories
  • Test concurrent entry handling
  • Test various edge cases (permissions, disk space, etc.)

4.3 End-to-End Tests

  • Test MCP server startup and tool registration
  • Test actual tool invocation through MCP protocol
  • Verify file output matches expected format
  • Test with different journal path configurations

Phase 5: Error Handling & Edge Cases

5.1 Filesystem Error Handling

  • Permission denied errors
  • Disk space issues
  • Invalid path specifications
  • Network drive disconnections

5.2 MCP Protocol Error Handling

  • Invalid tool parameters
  • Server communication failures
  • Graceful shutdown handling

5.3 Data Validation

  • Validate diary entry content (basic sanity checks)
  • Handle empty or extremely large entries
  • Path validation and sanitization

Phase 6: Build & Distribution

6.1 Build Pipeline

  • TypeScript compilation to JavaScript
  • Bundle creation for distribution
  • Source map generation for debugging

6.2 Executable Creation

  • Create standalone executable entry point
  • Add shebang for Unix systems
  • Test cross-platform compatibility

6.3 Package Configuration

  • Configure package.json for npm distribution
  • Add proper bin entry for global installation
  • Include necessary files in package

Phase 7: Documentation & Examples

7.1 README Documentation

  • Installation instructions
  • Usage examples
  • Command line options
  • Troubleshooting guide

7.2 MCP Configuration Examples

  • Example MCP server configuration
  • Integration examples with Claude Desktop
  • Sample journal entries (for documentation)

7.3 Developer Documentation

  • API documentation
  • Contribution guidelines
  • Architecture overview

Implementation Timeline

Week 1: Foundation

  • Project setup, dependencies, basic structure
  • Core journal writing logic
  • Command line argument handling

Week 2: MCP Integration

  • MCP server implementation
  • Tool registration and basic functionality
  • Initial testing

Week 3: Polish & Testing

  • Comprehensive test suite
  • Error handling
  • Edge case coverage

Week 4: Distribution & Documentation

  • Build pipeline
  • Documentation
  • Final testing and release preparation

Success Criteria

Functional Requirements

✅ MCP server starts successfully with stdio protocol ✅ process_feelings tool is properly registered and callable ✅ Journal entries are written to correct file structure ✅ Timestamps include microsecond precision ✅ Command line arguments work as specified ✅ Proper error messages for filesystem issues

Non-Functional Requirements

✅ Minimal memory footprint ✅ Fast journal entry writing (< 100ms typical) ✅ Reliable operation under normal usage ✅ Clear error messages for troubleshooting

Testing Requirements

✅ 90%+ code coverage with unit tests ✅ All integration tests pass ✅ End-to-end workflow verified ✅ Cross-platform compatibility confirmed

Risk Mitigation

Technical Risks

  • MCP Protocol Changes: Pin to stable MCP SDK version
  • Filesystem Issues: Comprehensive error handling and user feedback
  • Performance: Profile and optimize file operations

Scope Risks

  • Feature Creep: Strict adherence to v1 spec, defer v2 features
  • Over-Engineering: Keep implementation minimal and focused

Timeline Risks

  • Dependency Issues: Have backup plans for MCP SDK problems
  • Testing Complexity: Start testing early and iterate

Next Steps

  1. Begin with Phase 1: Project Setup
  2. Create initial Node.js project structure
  3. Install and configure MCP SDK
  4. Implement basic journal writing functionality
  5. Build iteratively with continuous testing