Portfolio

An MCP (Model Context Protocol) server that enables AI assistants like Claude to manage blog posts and projects for a personal portfolio site. Supports creating, reading, updating, and deleting MDX blog posts and project entries, with Git integration for committing and pushing changes.

How It Works

This server connects to a separate portfolio repository (e.g., suthar-portfolio) and provides tools for content management. It can run in three modes:

• Local MCP server -- Connects directly to Claude Desktop via stdio, reads and writes files on the local filesystem
• REST API server -- An Express HTTP server for web-based or programmatic access
• Vercel serverless deployment -- A serverless function that uses the GitHub API to read/write files without local filesystem access

Features

• Post Management: Full CRUD operations on MDX blog posts with YAML frontmatter
• Project Management: Full CRUD operations on the projectsData.js file
• Git Integration: View repository status and commit/push changes with a two-step confirmation workflow
• API Key Authentication: Bearer token auth for securing the REST API and Vercel endpoints
• CORS Support: Configurable origin restrictions
• MCP Proxy: A bridge that lets Claude Desktop connect to a remote Vercel-deployed backend

Setup

1. Install dependencies

npm install

2. Configure

Copy the example config and update it with the path to your portfolio repository:

cp portfolio-mcp.config.json.example portfolio-mcp.config.json

Edit portfolio-mcp.config.json:

{
  "portfolioPath": "/path/to/your/portfolio-repo",
  "postsDir": "data/posts",
  "projectsFile": "data/projectsData.js",
  "git": {
    "remote": "origin",
    "branch": "main",
    "requireConfirmation": true
  },
  "api": {
    "port": 3333,
    "host": "localhost"
  }
}

Alternatively, set environment variables (takes priority over the config file):

PORTFOLIO_PATH=/path/to/your/portfolio-repo
POSTS_DIR=data/posts
PROJECTS_FILE=data/projectsData.js
GIT_REMOTE=origin
GIT_BRANCH=main
API_PORT=3000
API_HOST=localhost
API_KEY=your-secret-key
ALLOWED_ORIGIN=https://yourdomain.com

3. Build

npm run build

Usage

MCP Server (Claude Desktop)

npm start

Add to your Claude Desktop claude_desktop_config.json:

{
  "mcpServers": {
    "portfolio-mcp": {
      "command": "node",
      "args": ["/path/to/portfolio-mcp/dist/index.js"],
      "cwd": "/path/to/portfolio-mcp"
    }
  }
}

REST API Server

npm run start:api

Development (ts-node, no build step)

npm run dev          # MCP server
npm run dev:api      # REST API server

MCP Tools

Tool	Description
list_posts	List all blog posts with frontmatter
get_post	Get a post's full content by slug
create_post	Create a new MDX blog post
update_post	Update an existing post's frontmatter or content
delete_post	Delete a post by slug
list_projects	List all projects
create_project	Add a new project
update_project	Update a project by title
delete_project	Remove a project by title
git_status	Show pending changes in the portfolio repo
git_commit_push	Commit and push changes (dry-run first, then confirm)

REST API Endpoints

All endpoints (except /health) require a Bearer token in the Authorization header when API_KEY is set.

Method	Path	Description
GET	/health	Health check (no auth required)
GET	/api/posts	List all posts
GET	/api/posts/:slug	Get a single post
POST	/api/posts	Create a post
PUT	/api/posts/:slug	Update a post
DELETE	/api/posts/:slug	Delete a post
GET	/api/projects	List all projects
POST	/api/projects	Create a project
PUT	/api/projects/:title	Update a project
DELETE	/api/projects/:title	Delete a project
GET	/api/git/status	Git status
POST	/api/git/commit-push	Commit and push

Data Formats

Blog Posts

MDX files with YAML frontmatter, stored in data/posts/:

---
title: 'Post Title'
date: '2024-06-27'
tags: [tag1, tag2, tag3]
draft: false
summary: 'Short description'
---

MDX body content here...

Optional frontmatter fields: pinned (boolean), pinnedtext (string).

Projects

Managed in data/projectsData.js as a JavaScript array:

const projectsData = [
  {
    title: 'Project Name',
    description: 'Description',
    imgSrc: '/image.jpg',
    href: 'https://example.com',
    github: 'https://github.com/...',
    tech1: 'React',
    tech2: 'TypeScript',
    tech3: 'Node.js'
  }
];
export default projectsData;

Required fields: title, description, imgSrc, href. Optional: github, tech1, tech2, tech3.

Git Workflow

The git_commit_push tool uses a two-step confirmation:

1. First call (without confirmed): Returns a dry-run preview of what would be committed
2. Second call (with confirmed: true): Executes the commit and push

This prevents accidental commits and lets the user review changes first.

Vercel Deployment

The api/portfolio.ts handler is a self-contained Vercel serverless function that uses the GitHub Contents API directly, so it does not require local filesystem access to the portfolio repo.

Required environment variables on Vercel

Variable	Description
GITHUB_TOKEN	GitHub personal access token with repo scope
GITHUB_OWNER	GitHub username (default: sohumsuthar)
GITHUB_REPO	Repository name (default: suthar-portfolio)
GITHUB_BRANCH	Branch to read/write (default: main)
API_KEY	Secret key for Bearer token auth
ALLOWED_ORIGIN	CORS allowed origin

MCP Proxy for Remote Access

To connect Claude Desktop to a Vercel-deployed backend, use the MCP proxy:

{
  "mcpServers": {
    "portfolio-mcp": {
      "command": "node",
      "args": ["/path/to/portfolio-mcp/dist/mcp-proxy.js"],
      "env": {
        "PORTFOLIO_API_URL": "https://your-deployment.vercel.app",
        "PORTFOLIO_API_KEY": "your-api-key"
      }
    }
  }
}

Security

• API key authentication via Bearer tokens
• CORS restricted to configured origins
• Environment variables for all secrets (never committed to git)
• Request logging on the REST API server
• Health check endpoint available without authentication

License

MIT