epic-me-mcp

# EpicMe MCP This is an example of an application that's exclusively accessible via Model Context Protocol (MCP). Everything from user registration and authentication to interacting with user data is handled via MCP tools. The goal is to demonstrate a possible future of applications where users interact with our apps via natural language with LLMs and the MCP protocol. This will also be the basis upon which I will teach how to build MCP tools on [EpicAI.pro](https://www.epicai.pro). ## How to Use **⚠️ Important Disclaimer: This is an experimental playground, not a production service. There are no SLAs, guarantees of data privacy, or data retention policies. Use at your own risk and don't store anything important or sensitive.** ### Server URL The EpicMe MCP server is deployed at: ``` https://epic-me-mcp.kentcdodds.workers.dev/mcp ``` ### What You Can Do EpicMe is a personal journaling application that allows you to: - **Create and manage journal entries** with titles, content, mood, location, weather, and privacy settings - **Organize entries with tags** for better categorization and filtering - **Get AI-powered tag suggestions** for your entries - **Summarize your journal entries** with optional filtering by tags or date range - **Mark entries as favorites** and set privacy levels ### Getting Started 1. **Connect to the MCP server** using your preferred MCP client (like [Claude Desktop](https://claude.ai/download)) 2. **Authenticate** by providing your email address - you'll receive a validation code 3. **Start journaling** using natural language commands ### Authentication Flow The authentication is unique because it works with users who don't exist yet: 1. Use the `authenticate` tool with your email address 2. Check your email for a TOTP validation code 3. Use the `validate_token` tool with the code to complete authentication 4. You're now logged in and can access all authenticated features ### Available Tools #### Authentication Tools (Unauthenticated) - **`authenticate`** - Start authentication process with your email - **`validate_token`** - Complete authentication with emailed validation code #### User Management Tools (Authenticated) - **`whoami`** - Get information about the current user - **`logout`** - Remove authentication #### Journal Entry Tools (Authenticated) - **`create_entry`** - Create a new journal entry with optional tags, mood, location, weather - **`get_entry`** - Retrieve a specific journal entry by ID - **`list_entries`** - List all entries, optionally filtered by tags - **`update_entry`** - Update any field of an existing entry - **`delete_entry`** - Delete a journal entry #### Tag Management Tools (Authenticated) - **`create_tag`** - Create a new tag for organizing entries - **`get_tag`** - Get details of a specific tag - **`list_tags`** - List all your tags - **`update_tag`** - Update tag properties - **`delete_tag`** - Delete a tag - **`add_tag_to_entry`** - Associate a tag with an entry ### Available Prompts - **`suggest_tags`** - Get AI-powered tag suggestions for a specific journal entry - **`summarize_journal_entries`** - Get a summary of your journal entries, with optional filtering by tags or date range ### Available Resources - **`epicme://credits`** - Credits information - **`epicme://users/current`** - Current user information - **`epicme://entries/{id}`** - Specific journal entry data - **`epicme://entries`** - List of all journal entries - **`epicme://tags/{id}`** - Specific tag data - **`epicme://tags`** - List of all tags ### Example Usage Here are some example natural language commands you can use: - "Authenticate me with my email address" - "Create a new journal entry about my day at the beach" - "List all my journal entries" - "Show me entries tagged with 'work'" - "Suggest tags for my latest entry" - "Summarize my journal entries from last week" - "Update my entry to mark it as a favorite" - "Create a new tag called 'personal goals'" ## Authentication The authentication flow is unique because we need to be able to go through OAuth for users who don't exist yet (users need to register first). So we generate a grant automatically without the user having to go through the OAuth flow themselves. Then we allow the user to claim the grant via a TOTP code which is emailed to them. This works well enough. ## Known Issues During development, if you delete the `.wrangler` directory, you're deleting the dynamically registered clients. Those clients don't know that their entries have been deleted so they won't attempt to re-register. In the MCP Inspector, you can go in the browser dev tools and clear the session storage and it will re-register. In other clients I do not know how to make them re-register.