mirror of
https://github.com/waynesutton/markdown-site.git
synced 2026-01-12 04:09:14 +00:00
update: setup fork config docs and featured image.
This commit is contained in:
Wayne Sutton
318
.cursor/plans/mcp_server_implementation_012bbe93.plan.md
Normal file
318
.cursor/plans/mcp_server_implementation_012bbe93.plan.md
Normal file
@@ -0,0 +1,318 @@
|
||||
---
|
||||
name: MCP Server Implementation
|
||||
overview: Add Model Context Protocol (MCP) server capability to enable AI tools like Cursor to read blog posts, pages, and homepage content from the Convex database. The server will be read-only, secure, and expose tools that wrap existing Convex queries.
|
||||
todos:
|
||||
- id: add-mcp-dependency
|
||||
content: Add @modelcontextprotocol/sdk to package.json dependencies and add mcp script
|
||||
status: pending
|
||||
- id: create-mcp-server
|
||||
content: Create scripts/mcp-server.ts with MCP protocol implementation, stdio transport, and 7 tools (list_posts, get_post, list_pages, get_page, get_homepage, search_content, export_all)
|
||||
status: pending
|
||||
dependencies:
|
||||
- add-mcp-dependency
|
||||
- id: create-blog-post
|
||||
content: Create content/blog/how-to-use-mcp-server.md with complete usage instructions, Cursor config example, and troubleshooting
|
||||
status: pending
|
||||
- id: update-docs
|
||||
content: Add MCP Server section to content/pages/docs.md with overview, quick start, and tool reference
|
||||
status: pending
|
||||
dependencies:
|
||||
- create-mcp-server
|
||||
- id: update-setup-guide
|
||||
content: Add MCP server mention to content/blog/setup-guide.md with link to detailed guide
|
||||
status: pending
|
||||
dependencies:
|
||||
- create-blog-post
|
||||
- id: update-siteconfig
|
||||
content: Review and optionally add minimal MCP config to src/config/siteConfig.ts (if needed for future extensibility)
|
||||
status: pending
|
||||
- id: update-files-md
|
||||
content: Add mcp-server.ts entry to files.md under Scripts section
|
||||
status: pending
|
||||
dependencies:
|
||||
- create-mcp-server
|
||||
- id: update-changelogs
|
||||
content: Add MCP feature entry to changelog.md and content/pages/changelog-page.md
|
||||
status: pending
|
||||
dependencies:
|
||||
- create-mcp-server
|
||||
- create-blog-post
|
||||
- id: update-readme
|
||||
content: Add MCP Server section to README.md with brief description and quick start
|
||||
status: pending
|
||||
dependencies:
|
||||
- create-mcp-server
|
||||
---
|
||||
|
||||
# MCP Server Implementation Plan
|
||||
|
||||
## Overview
|
||||
|
||||
Add MCP (Model Context Protocol) server capability to enable AI tools like Cursor to access blog content. The server runs locally, connects to Convex via HTTP client, and exposes read-only tools for accessing posts, pages, homepage data, and search functionality.
|
||||
|
||||
## Architecture
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
subgraph local[Local Machine]
|
||||
Cursor[Cursor/AI Client]
|
||||
MCPServer[MCP Server<br/>scripts/mcp-server.ts]
|
||||
end
|
||||
|
||||
subgraph cloud[Convex Cloud]
|
||||
ConvexDB[(Convex Database)]
|
||||
Queries[Convex Queries<br/>posts.ts, pages.ts, search.ts]
|
||||
end
|
||||
|
||||
Cursor -->|"MCP Protocol<br/>(stdio)"| MCPServer
|
||||
MCPServer -->|"ConvexHttpClient<br/>(HTTP)"| Queries
|
||||
Queries --> ConvexDB
|
||||
```
|
||||
|
||||
## Implementation Steps
|
||||
|
||||
### 1. Add MCP SDK Dependency
|
||||
|
||||
**File:** `package.json`
|
||||
|
||||
- Add `@modelcontextprotocol/sdk` to dependencies
|
||||
- Version: Use latest stable version (check npm registry)
|
||||
- Add `mcp` script: `"mcp": "tsx scripts/mcp-server.ts"`
|
||||
|
||||
### 2. Create MCP Server Script
|
||||
|
||||
**New File:** `scripts/mcp-server.ts`
|
||||
|
||||
**Key Components:**
|
||||
|
||||
- Import MCP SDK: `@modelcontextprotocol/sdk`
|
||||
- Use `ConvexHttpClient` pattern from `sync-posts.ts`
|
||||
- Load environment: Read `VITE_CONVEX_URL` from `.env.local` (development) or `.env.production.local` (production)
|
||||
- Implement stdio transport for MCP protocol
|
||||
- Use `Server` class from MCP SDK
|
||||
- Log to stderr (not stdout) to avoid corrupting JSON-RPC messages
|
||||
|
||||
**MCP Tools to Implement:**
|
||||
|
||||
1. **`list_posts`** - Get all published posts
|
||||
- Calls: `api.posts.getAllPosts`
|
||||
- Returns: Array of post metadata (no content)
|
||||
|
||||
2. **`get_post`** - Get single post by slug with full content
|
||||
- Args: `slug: string`
|
||||
- Calls: `api.posts.getPostBySlug`
|
||||
- Returns: Full post object with content
|
||||
|
||||
3. **`list_pages`** - Get all published pages
|
||||
- Calls: `api.pages.getAllPages`
|
||||
- Returns: Array of page metadata (no content)
|
||||
|
||||
4. **`get_page`** - Get single page by slug with full content
|
||||
- Args: `slug: string`
|
||||
- Calls: `api.pages.getPageBySlug`
|
||||
- Returns: Full page object with content
|
||||
|
||||
5. **`get_homepage`** - Get homepage structure and featured content
|
||||
- Calls: `api.posts.getFeaturedPosts`, `api.pages.getFeaturedPages`, `api.posts.getAllPosts` (limited)
|
||||
- Returns: Combined homepage data structure
|
||||
|
||||
6. **`search_content`** - Full text search across posts and pages
|
||||
- Args: `query: string`
|
||||
- Calls: `api.search.search`
|
||||
- Returns: Search results with snippets
|
||||
|
||||
7. **`export_all`** - Batch export all posts and pages with full content
|
||||
- Calls: Multiple queries to get all content
|
||||
- Returns: Complete content export
|
||||
|
||||
**Error Handling:**
|
||||
|
||||
- Validate Convex URL is set
|
||||
- Handle Convex query errors gracefully
|
||||
- Return user-friendly error messages
|
||||
- Never expose internal errors to MCP clients
|
||||
|
||||
**Security:**
|
||||
|
||||
- Read-only access (no mutations)
|
||||
- Uses existing public Convex queries
|
||||
- No authentication needed (public content)
|
||||
- Each user runs their own server locally
|
||||
|
||||
### 3. Create Blog Post with Usage Instructions
|
||||
|
||||
**New File:** `content/blog/how-to-use-mcp-server.md`
|
||||
|
||||
**Content Sections:**
|
||||
|
||||
- What is MCP and why use it
|
||||
- Prerequisites (Node.js, Convex deployment)
|
||||
- Installation steps
|
||||
- Starting the MCP server
|
||||
- Cursor configuration example
|
||||
- Available tools reference
|
||||
- Troubleshooting common issues
|
||||
- Security considerations
|
||||
|
||||
**Frontmatter:**
|
||||
|
||||
```yaml
|
||||
title: "How to Use the MCP Server"
|
||||
description: "Guide to setting up and using the Model Context Protocol server with Cursor and other AI tools"
|
||||
date: "2025-12-28"
|
||||
slug: "how-to-use-mcp-server"
|
||||
published: true
|
||||
tags: ["mcp", "cursor", "ai", "tutorial"]
|
||||
```
|
||||
|
||||
### 4. Update Documentation Files
|
||||
|
||||
**File:** `content/pages/docs.md`
|
||||
|
||||
Add new section "MCP Server" after "API Endpoints" section:
|
||||
|
||||
- Overview of MCP server capability
|
||||
- Quick start: installation and running
|
||||
- Available tools list with descriptions
|
||||
- Cursor configuration example
|
||||
- Link to detailed blog post
|
||||
|
||||
**File:** `content/blog/setup-guide.md`
|
||||
|
||||
Add subsection under "Next Steps" or create new section:
|
||||
|
||||
- Brief mention of MCP server capability
|
||||
- Link to detailed guide
|
||||
- Quick setup command reference
|
||||
|
||||
**File:** `src/config/siteConfig.ts`
|
||||
|
||||
Add optional MCP configuration (if needed for future features):
|
||||
|
||||
- Consider adding `mcpServer` config object for future extensibility
|
||||
- For now, keep it simple - server reads from environment variables
|
||||
|
||||
### 5. Update Reference Files
|
||||
|
||||
**File:** `files.md`
|
||||
|
||||
Add entry under "Scripts (`scripts/`)" section:
|
||||
|
||||
```markdown
|
||||
| `mcp-server.ts` | MCP server for AI tool integration (Cursor, etc.). Exposes read-only tools for accessing blog posts, pages, and search. Uses ConvexHttpClient to connect to Convex deployment. |
|
||||
```
|
||||
|
||||
**File:** `changelog.md`
|
||||
|
||||
Add entry at top:
|
||||
|
||||
```markdown
|
||||
## [Unreleased]
|
||||
|
||||
### Added
|
||||
|
||||
- MCP (Model Context Protocol) server for AI tool integration
|
||||
- Read-only access to blog posts, pages, homepage, and search
|
||||
- Local server connects to Convex via HTTP client
|
||||
- Exposes 7 tools: list_posts, get_post, list_pages, get_page, get_homepage, search_content, export_all
|
||||
- Cursor configuration support
|
||||
- Blog post: "How to Use the MCP Server"
|
||||
```
|
||||
|
||||
**File:** `content/pages/changelog-page.md`
|
||||
|
||||
Add same entry at top (before v1.38.0)
|
||||
|
||||
### 6. Update README.md
|
||||
|
||||
**File:** `README.md`
|
||||
|
||||
Add section "MCP Server" after "Fork Configuration" or in appropriate location:
|
||||
|
||||
- Brief description
|
||||
- Quick start command
|
||||
- Link to detailed documentation
|
||||
- Note about read-only access
|
||||
|
||||
## Technical Details
|
||||
|
||||
### Environment Variables
|
||||
|
||||
The MCP server reads `VITE_CONVEX_URL` from:
|
||||
|
||||
- `.env.local` (development)
|
||||
- `.env.production.local` (production)
|
||||
|
||||
Users can specify via environment variable or config file.
|
||||
|
||||
### MCP Server Pattern
|
||||
|
||||
Follow the TypeScript MCP server pattern from official docs:
|
||||
|
||||
- Use `Server` class from `@modelcontextprotocol/sdk`
|
||||
- Implement stdio transport
|
||||
- Define tools with proper schemas
|
||||
- Handle errors gracefully
|
||||
- Log to stderr only
|
||||
|
||||
### Convex Query Usage
|
||||
|
||||
All tools use existing public queries:
|
||||
|
||||
- `api.posts.getAllPosts`
|
||||
- `api.posts.getPostBySlug`
|
||||
- `api.posts.getFeaturedPosts`
|
||||
- `api.pages.getAllPages`
|
||||
- `api.pages.getPageBySlug`
|
||||
- `api.pages.getFeaturedPages`
|
||||
- `api.search.search`
|
||||
|
||||
No new Convex functions needed - leverages existing API.
|
||||
|
||||
## Security Considerations
|
||||
|
||||
1. **Read-only access**: Only queries, no mutations exposed
|
||||
2. **Public content only**: Uses same queries as public website
|
||||
3. **Local execution**: Server runs on user's machine
|
||||
4. **No authentication**: Blog content is public by design
|
||||
5. **Error handling**: Never expose internal errors or stack traces
|
||||
|
||||
## Testing Checklist
|
||||
|
||||
- [ ] MCP server starts without errors
|
||||
- [ ] All 7 tools respond correctly
|
||||
- [ ] Convex connection works (dev and prod)
|
||||
- [ ] Error handling works for missing Convex URL
|
||||
- [ ] Error handling works for invalid queries
|
||||
- [ ] Cursor can connect and use tools
|
||||
- [ ] Documentation is clear and complete
|
||||
- [ ] Blog post provides step-by-step instructions
|
||||
|
||||
## Files to Create
|
||||
|
||||
1. `scripts/mcp-server.ts` - Main MCP server implementation
|
||||
2. `content/blog/how-to-use-mcp-server.md` - Usage guide blog post
|
||||
|
||||
## Files to Update
|
||||
|
||||
1. `package.json` - Add dependency and script
|
||||
2. `content/pages/docs.md` - Add MCP Server section
|
||||
3. `content/blog/setup-guide.md` - Add MCP mention
|
||||
4. `src/config/siteConfig.ts` - Optional future config (minimal changes)
|
||||
5. `files.md` - Add script description
|
||||
6. `changelog.md` - Add feature entry
|
||||
7. `content/pages/changelog-page.md` - Add feature entry
|
||||
8. `README.md` - Add MCP Server section
|
||||
|
||||
## Dependencies
|
||||
|
||||
- `@modelcontextprotocol/sdk` - MCP SDK for TypeScript
|
||||
- Existing: `convex`, `dotenv`, `tsx` (already in package.json)
|
||||
|
||||
## Notes
|
||||
|
||||
- No newsletter or email features exposed (as requested)
|
||||
- Server is read-only for security
|
||||
- Uses existing Convex queries (no backend changes needed)
|
||||
- Follows same pattern as `sync-posts.ts` for Convex connection
|
||||
- Compatible with Cursor and other MCP clients
|
||||
Reference in New Issue
Block a user