diff --git a/README.md b/README.md index e9e56ad..96429f0 100644 --- a/README.md +++ b/README.md @@ -36,6 +36,8 @@ npm run sync # dev npm run sync:prod # production ``` +**MCP Server:** The site includes an HTTP-based Model Context Protocol (MCP) server at `/mcp` for AI tool integration. Connect Cursor, Claude Desktop, and other MCP clients to access blog content programmatically. See [How to Use the MCP Server](https://www.markdown.fast/how-to-use-mcp-server) for setup instructions. + ## Documentation - **[Setup Guide](https://www.markdown.fast/setup-guide)** - Complete fork and deployment guide diff --git a/TASK.md b/TASK.md index 9a01b69..182c798 100644 --- a/TASK.md +++ b/TASK.md @@ -7,10 +7,23 @@ ## Current Status -v1.38.0 ready. Improved newsletter CLI commands - `newsletter:send` now calls mutation directly and added `newsletter:send:stats` for sending weekly stats summary. Created blog post "How to use AgentMail with Markdown Sync" with complete setup guide. +v1.39.0 ready. HTTP-based MCP (Model Context Protocol) server deployed on Netlify Edge Functions. Accessible 24/7 at /mcp endpoint with public access (50 req/min) and optional API key authentication (1000 req/min). Seven tools available: list_posts, get_post, list_pages, get_page, get_homepage, search_content, export_all. Blog post "How to Use the MCP Server" includes setup instructions for forks. ## Completed +- [x] HTTP-based MCP Server on Netlify + - [x] Created netlify/edge-functions/mcp.ts with JSON-RPC 2.0 implementation + - [x] Added @modelcontextprotocol/sdk dependency to package.json + - [x] Configured Netlify rate limiting (50 req/min public, 1000 req/min authenticated) + - [x] Implemented optional authentication via Authorization header + - [x] Added /mcp edge function route to netlify.toml + - [x] Created blog post "How to Use the MCP Server" with fork setup instructions + - [x] Updated documentation (docs.md, setup-guide.md, files.md, changelog.md, README.md) + - [x] Added MCP configuration to siteConfig.ts + - [x] Seven tools implemented: list_posts, get_post, list_pages, get_page, get_homepage, search_content, export_all + - [x] CORS support for MCP clients + - [x] Manual JSON-RPC implementation (no SDK dependency on Deno runtime) + - [x] Newsletter CLI improvements - [x] Updated newsletter:send to call scheduleSendPostNewsletter mutation directly - [x] Added newsletter:send:stats command for weekly stats summary diff --git a/content/blog/how-to-use-mcp-server.md b/content/blog/how-to-use-mcp-server.md index ee5c1ea..67acb6b 100644 --- a/content/blog/how-to-use-mcp-server.md +++ b/content/blog/how-to-use-mcp-server.md @@ -1,9 +1,11 @@ --- -title: "How to Use the MCP Server" -description: "Guide to using the HTTP-based Model Context Protocol server at www.markdown.fast/mcp with Cursor and other AI tools" +title: "How to Use the MCP Server with MarkDown.fast" +description: "Guide to using the HTTP-based Model Context Protocol(MCP) server at www.markdown.fast/mcp with Cursor and other AI tools" date: "2025-12-28" slug: "how-to-use-mcp-server" +image: /images/mcp-blog.png published: true +blogFeatured: true tags: ["mcp", "cursor", "ai", "tutorial", "netlify"] --- @@ -34,15 +36,15 @@ No authentication is required for public access. The server exposes seven tools: -| Tool | Description | -|------|-------------| -| `list_posts` | Get all published blog posts with metadata | -| `get_post` | Get a single post by slug with full content | -| `list_pages` | Get all published pages | -| `get_page` | Get a single page by slug with full content | -| `get_homepage` | Get homepage data with featured and recent posts | -| `search_content` | Full text search across posts and pages | -| `export_all` | Batch export all content | +| Tool | Description | +| ---------------- | ------------------------------------------------ | +| `list_posts` | Get all published blog posts with metadata | +| `get_post` | Get a single post by slug with full content | +| `list_pages` | Get all published pages | +| `get_page` | Get a single page by slug with full content | +| `get_homepage` | Get homepage data with featured and recent posts | +| `search_content` | Full text search across posts and pages | +| `export_all` | Batch export all content | ## Client configuration @@ -209,12 +211,82 @@ The MCP server is designed with security in mind: ## For your own fork -When you fork this site, the MCP server automatically connects to your Convex deployment. Just ensure: +When you fork this site, the MCP server is already included and will automatically connect to your Convex deployment. Here's how to set it up: -1. `VITE_CONVEX_URL` is set in your Netlify environment variables -2. (Optional) Set `MCP_API_KEY` for authenticated access +### Prerequisites -The server reads from your Convex database, so any content you sync will be available via MCP. +1. Fork the repository to your GitHub account +2. Set up Convex backend (see [Setup Guide](/setup-guide)) +3. Deploy to Netlify (see [Setup Guide](/setup-guide)) + +### Setup Steps + +1. **Set Convex URL in Netlify** + + The MCP server needs your Convex deployment URL to fetch content. Add this environment variable in your Netlify dashboard: + - Go to Site Settings > Environment Variables + - Add `VITE_CONVEX_URL` with your production Convex URL (e.g., `https://your-deployment.convex.cloud`) + +2. **Deploy your site** + + The MCP server is already configured in `netlify/edge-functions/mcp.ts` and `netlify.toml`. When you deploy to Netlify, the server will be available at: + + ``` + https://your-site.netlify.app/mcp + ``` + + Or your custom domain: + + ``` + https://yourdomain.com/mcp + ``` + +3. **Optional: Set API key for higher rate limits** + + If you want authenticated access with higher rate limits: + - Add `MCP_API_KEY` to your Netlify environment variables + - Use this key in your client configuration (see "With API key" section above) + +### How it works + +The MCP server reads from your Convex database using the same queries as your public website. Any content you sync with `npm run sync` or `npm run sync:prod` will be immediately available via the MCP server. + +### Testing your fork's MCP server + +After deploying, test your MCP server: + +```bash +# Replace with your site URL +curl -X POST https://your-site.netlify.app/mcp \ + -H "Content-Type: application/json" \ + -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' +``` + +You should receive a response listing all seven available tools. + +### Client configuration for your fork + +Update your Cursor or Claude Desktop configuration to use your fork's endpoint: + +```json +{ + "mcpServers": { + "my-blog": { + "url": "https://your-site.netlify.app/mcp" + } + } +} +``` + +### Files included + +The MCP server implementation is included in your fork: + +- `netlify/edge-functions/mcp.ts` - MCP server implementation +- `netlify.toml` - Edge function route configuration +- `package.json` - Includes `@modelcontextprotocol/sdk` dependency + +No additional code changes needed. Just set the environment variable and deploy. ## Troubleshooting @@ -233,6 +305,7 @@ Verify the tool name matches one of the seven available tools exactly. ### Invalid JSON-RPC Ensure your request includes: + - `"jsonrpc": "2.0"` - A numeric or string `id` - A `method` string diff --git a/public/images/mcp-blog.png b/public/images/mcp-blog.png new file mode 100644 index 0000000..565c842 Binary files /dev/null and b/public/images/mcp-blog.png differ diff --git a/public/raw/changelog.md b/public/raw/changelog.md index 0ae00f0..38f7464 100644 --- a/public/raw/changelog.md +++ b/public/raw/changelog.md @@ -8,6 +8,52 @@ Date: 2025-12-28 All notable changes to this project. ![](https://img.shields.io/badge/License-MIT-yellow.svg) +## v1.39.0 + +Released December 28, 2025 + +**HTTP-based MCP Server** + +- Model Context Protocol (MCP) server deployed on Netlify Edge Functions + - Accessible 24/7 at `https://www.markdown.fast/mcp` + - No local machine required (unlike stdio-based MCP servers) + - Works with Cursor, Claude Desktop, and other MCP-compatible clients +- Public access with Netlify built-in rate limiting (50 req/min per IP) +- Optional API key authentication for higher limits (1000 req/min) + - Set `MCP_API_KEY` in Netlify environment variables + - Add `Authorization: Bearer ` header to requests +- Read-only access to blog content: + - `list_posts`: Get all published posts with metadata + - `get_post`: Get single post by slug with full content + - `list_pages`: Get all published pages + - `get_page`: Get single page by slug with full content + - `get_homepage`: Get homepage data with featured and recent posts + - `search_content`: Full text search across posts and pages + - `export_all`: Batch export all content + +**Documentation** + +- Blog post: "How to Use the MCP Server" with client configuration examples +- MCP Server section added to docs.md +- MCP configuration added to siteConfig.ts +- Setup guide updated with MCP server section + +**Configuration** + +Add to Cursor (`~/.cursor/mcp.json`): + +```json +{ + "mcpServers": { + "markdown-fast": { + "url": "https://www.markdown.fast/mcp" + } + } +} +``` + +Updated files: `netlify/edge-functions/mcp.ts`, `netlify.toml`, `package.json`, `src/config/siteConfig.ts`, `content/blog/how-to-use-mcp-server.md`, `content/pages/docs.md`, `content/blog/setup-guide.md`, `files.md`, `changelog.md`, `content/pages/changelog-page.md` + ## v1.38.0 Released December 27, 2025 diff --git a/public/raw/docs.md b/public/raw/docs.md index 0764354..baab48d 100644 --- a/public/raw/docs.md +++ b/public/raw/docs.md @@ -979,6 +979,49 @@ The `newsletter:send` command calls the `scheduleSendPostNewsletter` mutation di | `/openapi.yaml` | OpenAPI 3.0 specification | | `/llms.txt` | AI agent discovery | +## MCP Server + +The site includes an HTTP-based Model Context Protocol (MCP) server for AI tool integration. It allows AI assistants like Cursor and Claude Desktop to access blog content programmatically. + +**Endpoint:** `https://www.markdown.fast/mcp` + +**Features:** + +- 24/7 availability via Netlify Edge Functions +- Public access with rate limiting (50 req/min per IP) +- Optional API key for higher limits (1000 req/min) +- Read-only access to content + +**Available tools:** + +| Tool | Description | +|------|-------------| +| `list_posts` | Get all published blog posts with metadata | +| `get_post` | Get a single post by slug with full content | +| `list_pages` | Get all published pages | +| `get_page` | Get a single page by slug with full content | +| `get_homepage` | Get homepage data with featured and recent posts | +| `search_content` | Full text search across posts and pages | +| `export_all` | Batch export all content | + +**Cursor configuration:** + +Add to `~/.cursor/mcp.json`: + +```json +{ + "mcpServers": { + "markdown-fast": { + "url": "https://www.markdown.fast/mcp" + } + } +} +``` + +**For forks:** The MCP server automatically connects to your Convex deployment. Ensure `VITE_CONVEX_URL` is set in Netlify. Optionally set `MCP_API_KEY` for authenticated access with higher rate limits. + +See [How to Use the MCP Server](/how-to-use-mcp-server) for full documentation. + ## Raw markdown files When you run `npm run sync` (development) or `npm run sync:prod` (production), static `.md` files are generated in `public/raw/` for each published post and page. Use `npm run sync:all` or `npm run sync:all:prod` to sync content and update discovery files together. diff --git a/public/raw/how-to-use-mcp-server.md b/public/raw/how-to-use-mcp-server.md new file mode 100644 index 0000000..3247fc7 --- /dev/null +++ b/public/raw/how-to-use-mcp-server.md @@ -0,0 +1,317 @@ +# How to Use the MCP Server with MarkDown.fast + +> Guide to using the HTTP-based Model Context Protocol(MCP) server at www.markdown.fast/mcp with Cursor and other AI tools + +--- +Type: post +Date: 2025-12-28 +Reading time: 5 min read +Tags: mcp, cursor, ai, tutorial, netlify +--- + +This site includes an HTTP-based Model Context Protocol (MCP) server that allows AI tools like Cursor, Claude Desktop, and other MCP-compatible clients to access blog content programmatically. + +## What is MCP? + +The Model Context Protocol is an open standard for connecting AI applications to external data sources. It enables AI assistants to read content, search, and retrieve information from connected systems. + +Our MCP server exposes read-only tools for accessing: + +- Blog posts (list, get by slug, search) +- Static pages (list, get by slug) +- Homepage data (featured content, recent posts) +- Full content export + +## Endpoint URL + +The MCP server is available 24/7 at: + +``` +https://www.markdown.fast/mcp +``` + +No authentication is required for public access. + +## Available tools + +The server exposes seven tools: + +| Tool | Description | +| ---------------- | ------------------------------------------------ | +| `list_posts` | Get all published blog posts with metadata | +| `get_post` | Get a single post by slug with full content | +| `list_pages` | Get all published pages | +| `get_page` | Get a single page by slug with full content | +| `get_homepage` | Get homepage data with featured and recent posts | +| `search_content` | Full text search across posts and pages | +| `export_all` | Batch export all content | + +## Client configuration + +### Cursor + +Add to your Cursor MCP configuration file (`~/.cursor/mcp.json`): + +```json +{ + "mcpServers": { + "markdown-fast": { + "url": "https://www.markdown.fast/mcp" + } + } +} +``` + +### Claude Desktop + +Add to your Claude Desktop configuration: + +```json +{ + "mcpServers": { + "markdown-fast": { + "url": "https://www.markdown.fast/mcp" + } + } +} +``` + +### With API key (optional) + +If you have an API key for higher rate limits: + +```json +{ + "mcpServers": { + "markdown-fast": { + "url": "https://www.markdown.fast/mcp", + "headers": { + "Authorization": "Bearer your-api-key-here" + } + } + } +} +``` + +## Rate limiting + +The server uses Netlify's built-in rate limiting: + +- **Public access**: 50 requests per minute per IP address +- **Authenticated access**: Higher limits with API key + +When rate limited, the server returns HTTP 429. Wait a minute before retrying. + +## Example requests + +### Initialize connection + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "initialize", + "params": { + "protocolVersion": "2024-11-05", + "capabilities": {}, + "clientInfo": { + "name": "my-client", + "version": "1.0.0" + } + } +} +``` + +### List available tools + +```json +{ + "jsonrpc": "2.0", + "id": 2, + "method": "tools/list" +} +``` + +### Get all posts + +```json +{ + "jsonrpc": "2.0", + "id": 3, + "method": "tools/call", + "params": { + "name": "list_posts", + "arguments": {} + } +} +``` + +### Get a specific post + +```json +{ + "jsonrpc": "2.0", + "id": 4, + "method": "tools/call", + "params": { + "name": "get_post", + "arguments": { + "slug": "setup-guide" + } + } +} +``` + +### Search content + +```json +{ + "jsonrpc": "2.0", + "id": 5, + "method": "tools/call", + "params": { + "name": "search_content", + "arguments": { + "query": "markdown" + } + } +} +``` + +## Testing with curl + +Test the server directly: + +```bash +# Initialize +curl -X POST https://www.markdown.fast/mcp \ + -H "Content-Type: application/json" \ + -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' + +# List tools +curl -X POST https://www.markdown.fast/mcp \ + -H "Content-Type: application/json" \ + -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' + +# Get all posts +curl -X POST https://www.markdown.fast/mcp \ + -H "Content-Type: application/json" \ + -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_posts","arguments":{}}}' +``` + +## Security + +The MCP server is designed with security in mind: + +- **Read-only access**: No mutations or writes are exposed +- **Public content**: Uses the same queries as the public website +- **Rate limiting**: Prevents abuse via Netlify's built-in rate limiting +- **HTTPS encryption**: All traffic is encrypted +- **Optional authentication**: API keys available for higher limits + +## For your own fork + +When you fork this site, the MCP server is already included and will automatically connect to your Convex deployment. Here's how to set it up: + +### Prerequisites + +1. Fork the repository to your GitHub account +2. Set up Convex backend (see [Setup Guide](/setup-guide)) +3. Deploy to Netlify (see [Setup Guide](/setup-guide)) + +### Setup Steps + +1. **Set Convex URL in Netlify** + + The MCP server needs your Convex deployment URL to fetch content. Add this environment variable in your Netlify dashboard: + - Go to Site Settings > Environment Variables + - Add `VITE_CONVEX_URL` with your production Convex URL (e.g., `https://your-deployment.convex.cloud`) + +2. **Deploy your site** + + The MCP server is already configured in `netlify/edge-functions/mcp.ts` and `netlify.toml`. When you deploy to Netlify, the server will be available at: + + ``` + https://your-site.netlify.app/mcp + ``` + + Or your custom domain: + + ``` + https://yourdomain.com/mcp + ``` + +3. **Optional: Set API key for higher rate limits** + + If you want authenticated access with higher rate limits: + - Add `MCP_API_KEY` to your Netlify environment variables + - Use this key in your client configuration (see "With API key" section above) + +### How it works + +The MCP server reads from your Convex database using the same queries as your public website. Any content you sync with `npm run sync` or `npm run sync:prod` will be immediately available via the MCP server. + +### Testing your fork's MCP server + +After deploying, test your MCP server: + +```bash +# Replace with your site URL +curl -X POST https://your-site.netlify.app/mcp \ + -H "Content-Type: application/json" \ + -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' +``` + +You should receive a response listing all seven available tools. + +### Client configuration for your fork + +Update your Cursor or Claude Desktop configuration to use your fork's endpoint: + +```json +{ + "mcpServers": { + "my-blog": { + "url": "https://your-site.netlify.app/mcp" + } + } +} +``` + +### Files included + +The MCP server implementation is included in your fork: + +- `netlify/edge-functions/mcp.ts` - MCP server implementation +- `netlify.toml` - Edge function route configuration +- `package.json` - Includes `@modelcontextprotocol/sdk` dependency + +No additional code changes needed. Just set the environment variable and deploy. + +## Troubleshooting + +### Server returns 500 error + +Check that `VITE_CONVEX_URL` is set in your Netlify environment variables. + +### Rate limit exceeded + +Wait 60 seconds before retrying. Consider using an API key for higher limits. + +### Tool not found + +Verify the tool name matches one of the seven available tools exactly. + +### Invalid JSON-RPC + +Ensure your request includes: + +- `"jsonrpc": "2.0"` +- A numeric or string `id` +- A `method` string + +## Resources + +- [Model Context Protocol specification](https://modelcontextprotocol.io) +- [Cursor MCP documentation](https://docs.cursor.com/context/model-context-protocol) +- [Claude Desktop MCP setup](https://claude.ai/docs/mcp) \ No newline at end of file diff --git a/public/raw/index.md b/public/raw/index.md index f74d2da..fd6642a 100644 --- a/public/raw/index.md +++ b/public/raw/index.md @@ -2,8 +2,10 @@ This is the homepage index of all published content. -## Blog Posts (13) +## Blog Posts (14) +- **[How to Use the MCP Server with MarkDown.fast](/raw/how-to-use-mcp-server.md)** - Guide to using the HTTP-based Model Context Protocol(MCP) server at www.markdown.fast/mcp with Cursor and other AI tools + - Date: 2025-12-28 | Reading time: 5 min read | Tags: mcp, cursor, ai, tutorial, netlify - **[How to use AgentMail with Markdown Sync](/raw/how-to-use-agentmail.md)** - Complete guide to setting up AgentMail for newsletters and contact forms in your markdown blog - Date: 2025-12-27 | Reading time: 5 min read | Tags: agentmail, newsletter, email, setup - **[How to use Firecrawl](/raw/how-to-use-firecrawl.md)** - Import external articles as markdown posts using Firecrawl. Get your API key and configure environment variables for local imports and AI chat. @@ -42,6 +44,6 @@ This is the homepage index of all published content. --- -**Total Content:** 13 posts, 6 pages +**Total Content:** 14 posts, 6 pages All content is available as raw markdown files at `/raw/{slug}.md` diff --git a/public/raw/setup-guide.md b/public/raw/setup-guide.md index e46d75b..dbaaf2a 100644 --- a/public/raw/setup-guide.md +++ b/public/raw/setup-guide.md @@ -1590,4 +1590,36 @@ After deploying: 4. Submit your sitemap to Google Search Console 5. Share your first post -Your blog is now live with real-time updates, SEO optimization, and AI-friendly APIs. Every time you sync new posts, they appear immediately without redeploying. \ No newline at end of file +Your blog is now live with real-time updates, SEO optimization, and AI-friendly APIs. Every time you sync new posts, they appear immediately without redeploying. + +## MCP Server + +Your site includes an HTTP-based Model Context Protocol (MCP) server for AI tool integration. + +**Endpoint:** `https://your-site.netlify.app/mcp` + +The MCP server runs 24/7 on Netlify Edge Functions and allows AI assistants like Cursor and Claude Desktop to access your blog content programmatically. No local machine required. + +**Features:** + +- Public access with rate limiting (50 req/min per IP) +- Optional API key for higher limits (1000 req/min) +- Seven tools: list_posts, get_post, list_pages, get_page, get_homepage, search_content, export_all + +**Configuration:** + +Add to your Cursor config (`~/.cursor/mcp.json`): + +```json +{ + "mcpServers": { + "my-blog": { + "url": "https://your-site.netlify.app/mcp" + } + } +} +``` + +**For higher rate limits:** Set `MCP_API_KEY` in your Netlify environment variables, then add the Authorization header to your client config. + +See [How to Use the MCP Server](/how-to-use-mcp-server) for full documentation. \ No newline at end of file diff --git a/src/pages/Home.tsx b/src/pages/Home.tsx index 82de82d..96535e9 100644 --- a/src/pages/Home.tsx +++ b/src/pages/Home.tsx @@ -99,7 +99,6 @@ export default function Home() { {/* Intro with JSX support for links */}

An open-source publishing framework built for AI agents and developers -

to ship websites, docs, or blogs.


Write markdown, sync from the terminal.{" "} - )} + {siteConfig.socialFooter?.enabled && + siteConfig.socialFooter.showOnHomepage && } ); }