# portfolio-mcp

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

```bash
npm install
```

### 2. Configure

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

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

Edit `portfolio-mcp.config.json`:

```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

```bash
npm run build
```

## Usage

### MCP Server (Claude Desktop)

```bash
npm start
```

Add to your Claude Desktop `claude_desktop_config.json`:

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

### REST API Server

```bash
npm run start:api
```

### Development (ts-node, no build step)

```bash
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/`:

```yaml
---
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:

```js
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:

```json
{
  "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