MCP-Blog: One-Command Astro Blog Deployment to GitHub Pages

Publishing a new post means:

Write the article in the geyuxu.com blog project
Run git add ., git commit -m "...", and git push
Execute npm run build to generate static files in dist/
Push dist/ contents to the gh-pages branch

This involves multiple commands and risks, especially if Git doesn't track the dist/ directory correctly. More frustrating: I wanted one central place to handle this automation rather than scattered shell scripts across project directories.

So I built MCP-Blog: a tool to automate the entire commit-and-deploy workflow from a separate management directory using a single command.

This solves two problems:

Operational Isolation: Management logic lives outside the blog repository, keeping it clean
Process Simplification: Five-step workflow becomes one command, reducing mistakes

2. Technical Architecture: The Protocol Approach

Custom Protocol, Not Network Standard

I designed what I call "MCP"—a command-line interaction specification for this project. The idea is simple:

One independent execution script (the Model) understands and operates on a target project within a specific context (Context).

Here:

Model: The mcp-blog project—the active executor
Context: The geyuxu.com blog project—the target
Protocol: Our command-line interface, e.g., ./mcp.sh "commit message"

Architecture Diagram

The workflow is straightforward:

+-----------+       +-------------------------+       +---------------------+       +----------------+
|           |       |                         |       |                     |       |                |
|   User    |------>|  MCP Script (mcp.sh)    |------>|  Astro Blog Project |------>|  GitHub Repo   |
|           |       |                         |       | (geyuxu.com)        |       | (main/gh-pages)|
+-----------+       +-------------------------+       +---------------------+       +----------------+
      |                        |                                |                           |
      | 1. Provide commit msg  | 2. cd to blog directory       | 3. Git ops & build       | 4. Deploy to Pages
      |                        | 4. Execute deploy commands     |                           |

The key: how the MCP script effectively enters the Astro blog project directory and executes operations.

3. Implementation: Core Script and Automation

The entire system runs from a single Shell script.

Project Structure:

/Users/geyuxu/repo/blog/
├── mcp-blog/         # MCP project
│   └── mcp.sh
└── geyuxu.com/       # Astro blog project
    ├── src/
    ├── public/
    ├── package.json
    └── ...

1. Core Script `mcp.sh`

#!/bin/bash

# Exit immediately on error
set -e

# --- Configuration ---
# Define MCP project path (where the script resides)
MCP_PROJECT_PATH="/Users/geyuxu/repo/blog/mcp-blog"
# Define blog repository path (target to operate on)
BLOG_REPO_PATH="/Users/geyuxu/repo/blog/geyuxu.com"
# --- End Configuration ---

# 1. Check input parameters: commit message is required
if [ -z "$1" ]; then
  echo "❌ Error: Please provide a commit message."
  echo "Usage: ./mcp.sh \"your commit message\""
  exit 1
fi

COMMIT_MESSAGE=$1

echo "🚀 MCP-Blog task starting..."
echo "================================="

# 2. Cross-directory permission management core
echo "📂 Entering blog repository: $BLOG_REPO_PATH"
cd "$BLOG_REPO_PATH"

# 3. Git automation: commit source code
echo "🔄 Syncing source code to main branch..."
git add .
git commit -m "$COMMIT_MESSAGE"
git push origin main

echo "✅ Source sync complete."
echo "================================="

# 4. Astro blog system integration: build project
echo "🛠️  Building Astro project..."
npm run build

echo "✅ Build complete."
echo "================================="

# 5. GitHub Pages deployment
echo "🚀 Deploying to GitHub Pages..."
# We use the gh-pages package to simplify deployment
# It automatically pushes dist directory contents to gh-pages branch
npm run deploy

echo "✅ Deployment successful!"
echo "================================="
echo "🎉 All tasks completed, blog updated!"

# Return to original directory (optional, good practice)
cd "$MCP_PROJECT_PATH"

2. Key Technical Points

Cross-directory execution (cd "$BLOG_REPO_PATH"):
The cd command is fundamental. After startup, the script switches into the blog project directory. All subsequent git and npm commands then execute as if run directly from geyuxu.com, naturally gaining permission to operate on its files.

Git workflow (git add/commit/push):
The script commits source code using standard Git commands. Passing the commit message as the first parameter ($1) adds flexibility.

Astro build (npm run build):
Each Astro project defines a build script in package.json. Our script calls it directly without concerns about internal build details, achieving clean separation.

GitHub Pages deployment (npm run deploy):
I recommend the gh-pages npm package for simplicity. Install it in your Astro project (geyuxu.com):

npm install gh-pages --save-dev

Then add a deploy script to your geyuxu.com/package.json:

{
  "scripts": {
    "dev": "astro dev",
    "start": "astro dev",
    "build": "astro build",
    "preview": "astro preview",
    "astro": "astro",
    "deploy": "gh-pages -d dist" 
  }
}

The gh-pages -d dist command automatically pushes the dist directory to the gh-pages branch.

4. Usage: Publishing in One Command

Once configured, publishing is straightforward.

Grant execution permissions (once only):

cd /Users/geyuxu/repo/blog/mcp-blog
chmod +x mcp.sh

Publish:
After finishing your article in geyuxu.com, run:
```
./mcp.sh "feat: add new article about MCP-Blog"
```

Watch the automation unfold:

🚀 MCP-Blog task starting...
=================================
📂 Entering blog repository: /Users/geyuxu/repo/blog/geyuxu.com
🔄 Syncing source code to main branch...
[main 1234567] feat: add new article about MCP-Blog
 1 file changed, 1 insertion(+)
 ...
✅ Source sync complete.
=================================
🛠️  Building Astro project...
> [email protected] build
> astro build
...
✅ Build complete.
=================================
🚀 Deploying to GitHub Pages...
> [email protected] deploy
> gh-pages -d dist
Published
✅ Deployment successful!
=================================
🎉 All tasks completed, blog updated!

In minutes, your new article is live.

5. Results and Next Steps

MCP-Blog automates the publishing workflow through a simple Shell script:

Efficiency: Five-step process becomes one command
Reliability: Automation prevents manual errors
Separation: Management logic stays outside the blog repository

Possible next steps:

Create articles via CLI: Add ./mcp.sh new "Article Title" to auto-generate Markdown with frontmatter
Upgrade to Node.js or Python: Build a more robust CLI tool with better error handling and richer interaction
Migrate to GitHub Actions: Let the main branch push trigger automatic build and deployment—the ultimate automation

Delegation to automation lets us focus on what matters: creating better content.