MCP House Rules Server

Stop re-explaining yourself to AI assistants. This MCP (Model Context Protocol) server exposes reusable "house rules" as prompts and provides automatic git context, so you can focus on what you actually want to do instead of repeating the same setup instructions.

What Problem Does This Solve?

If you use AI assistants daily, you've probably experienced this loop:

1. You open Cursor or VS Code and ask it to review a PR
2. It asks where the repo is, what branch, what you want checked
3. You paste the same context you pasted yesterday
4. You switch to another client and do it again

This project solves two problems:

• Prompt reuse: Your "house rules" for how you want the assistant to behave are published once and discoverable by any MCP client
• Context reuse: Basic git information (branch, recent commits, diffstat) is fetched automatically so the assistant stops asking basic questions

What This Project Provides

1. House Rules Prompt

A reusable prompt template named house_rules that defines your preferred assistant behavior:

• Prefer safe and reversible actions (start read-only)
• Summarize before acting
• Keep scope small
• Be explicit with checklists
• Ask one clarifying question only when truly blocked

The prompt accepts an optional mode parameter (e.g., "review", "triage", "release-notes") to adapt the behavior for different workflows.

2. Git Context Tool

A tool named git_context that automatically fetches:

• Current branch name
• Recent commit history (configurable, default 15 commits)
• Latest commit diffstat

This eliminates the back-and-forth of "which repo?", "which branch?", "what changed?"

Project Structure

mcp-house-rules/
├── src/
│   └── index.ts                  # Main MCP server implementation
├── dist/                         # Compiled JavaScript (generated)
├── package.json                  # Dependencies and scripts
├── tsconfig.json                 # TypeScript configuration
├── mcp_Prompts_Screenshot.png    # MCP Inspector prompts demo
├── mcp_Tools_Screenshot.png      # MCP Inspector tools demo
└── README.md                     # This file

Components Explained

MCP Server (src/index.ts)

The server implements three main handlers:

1. ListPromptsHandler: Exposes the house_rules prompt so clients can discover it
2. GetPromptHandler: Returns the actual prompt content with optional mode customization
3. ListToolsHandler: Exposes the git_context tool
4. CallToolHandler: Executes git_context by running git commands and returning formatted results

Key Features

• Stdio Transport: Uses standard input/output for communication (required for MCP)
• Error Handling: Validates git repository before attempting operations
• Logging: All logs go to stderr (stdout is reserved for protocol messages)
• Type Safety: Uses Zod for runtime validation of tool arguments

Installation

1. Clone or download this repository
2. Install dependencies:

npm install

3. Build the TypeScript code:

npm run build

4. Test the server:

npm start

You should see a log message on stderr indicating the server is running.

Testing with MCP Inspector

Before wiring this into your AI client, test it with the MCP Inspector. This helps you debug and verify the server works correctly.

Step 1: Start MCP Inspector

npx @modelcontextprotocol/inspector

This opens a web UI in your browser (usually at http://localhost:5173).

Step 2: Configure the Connection

In the left sidebar of MCP Inspector:

1. Transport Type: Select STDIO
2. Command: Enter node
3. Arguments: Enter the absolute path to your compiled server:

   /Users/sanjay/personalProjects/mcpHouseRules/dist/index.js
   

Step 3: Connect

Click the "▷ Connect" button. You should see:

• Status changes to "Connected"
• Server name: mcp-house-rules
• Version: 0.1.0

Step 4: Test the Prompts

Go to the Prompts tab and select house_rules:

1. Click on house_rules in the left panel
2. In the mode field, type a mode like review, triage, or release-notes (plain text, not JSON)
3. Click "Get Prompt"
4. You should see your operating rules returned with the mode applied

Note: The mode field is a free-form text input. Just type the mode name directly (e.g., review), not JSON syntax.

Step 5: Test the Tools

Go to the Tools tab and select git_context:

1. Click on git_context in the left panel
2. Enter the repoPath: /Users/sanjay/personalProjects/mcpHouseRules (use an absolute path to any git repository)
3. Set maxCommits to 15 (or any number 1-50)
4. Click "Run Tool"
5. You should see the repo context: branch name, recent commits, and diffstat

Verification Checklist

• ✅ Prompts list includes house_rules
• ✅ Tools list includes git_context
• ✅ Calling house_rules returns your operating rules with the mode applied
• ✅ Calling git_context returns a compact repo context bundle

Troubleshooting

Server doesn't connect:

• Verify the path to dist/index.js is correct (use absolute path)
• Make sure you've built the project: npm run build
• Check that no other process is using the server

Prompt returns an error:

• Make sure the mode field contains plain text (e.g., review), not JSON
• The mode is optional; leaving it empty defaults to general

Tool returns "Not a git repository":

• Verify the repoPath is an absolute path to a valid git repository
• The directory must contain a .git folder

Integration with MCP Clients

Different MCP clients have different configuration formats, but the setup is similar:

1. Register the server as a local process
2. Set the command to: node + absolute path to dist/index.js
3. The client will discover prompts and tools automatically

Example Configuration (Cursor)

In your Cursor MCP settings, add:

{
  "mcpServers": {
    "house-rules": {
      "command": "node",
      "args": ["/absolute/path/to/mcpHouseRules/dist/index.js"]
    }
  }
}

Daily Usage Example

Once integrated, your workflow becomes:

1. Apply the house_rules prompt (with optional mode):

   Apply house_rules in review mode
   

2. Call git_context for your repository:

   Call git_context on /absolute/path/to/repo with 15 commits
   

3. Ask for what you actually want:

   Summarize what changed recently, flag risky areas, and give me a short checklist for what to verify before merging.
   

What changed compared to normal prompting:

• ✅ You're not retyping rules every time
• ✅ You're not answering "what branch is this"
• ✅ The assistant starts from a compact, consistent context bundle

Understanding Prompts vs Tools

This MCP server exposes both prompts and tools, which work differently in the MCP protocol:

Prompts (house_rules)

What they are:

• Reusable conversation templates that set context and behavior
• Discovered by the client and applied automatically
• Not directly callable as functions

How they work:

• The client (Cursor, VS Code, etc.) discovers available prompts
• When you reference a prompt, the client retrieves it and applies it to the conversation
• The prompt content becomes part of the conversation context

How to verify it's working:

1. In MCP Inspector:

   • Go to the "Prompts" tab
   • You should see house_rules listed
   • Click "Get Prompt" to see the prompt content
   • ✅ If you see the prompt content, it's discoverable and working

2. In Cursor:

   • After adding to mcp.json and restarting, go to Settings → Tools & MCP
   • Check that "house-rules" shows "1 prompt" available
   • ✅ If the prompt count is correct, it's discoverable
   • The prompt will be applied automatically when the client uses it

Note: Prompts are not callable as tools. They're templates that the client uses to set conversation context.

Tools (git_context)

What they are:

• Executable functions that perform actions
• Directly callable by the AI assistant
• Return data or perform operations

How they work:

• The assistant can call tools directly using their names
• Tools execute and return results
• Results are used in the conversation

How to verify it's working:

1. In MCP Inspector:

   • Go to the "Tools" tab
   • You should see git_context listed
   • Enter a repo path and click "Run Tool"
   • ✅ If you get repo context back, the tool is functional

2. In Cursor:

   • After adding to mcp.json and restarting, go to Settings → Tools & MCP
   • Check that "house-rules" shows "1 tool" available
   • ✅ If the tool count is correct, it's discoverable
   • Try: "Use git_context to get context for /path/to/repo"
   • ✅ If the assistant successfully calls it and returns data, it's working

Verification Checklist

Server Connection:

• ✅ Server appears in Cursor's Tools & MCP settings
• ✅ Shows correct version (0.1.0)
• ✅ Status is "Connected"

Prompt Verification:

• ✅ house_rules appears in MCP Inspector's Prompts tab
• ✅ Can retrieve prompt content in MCP Inspector
• ✅ Cursor shows "1 prompt" for house-rules server

Tool Verification:

• ✅ git_context appears in MCP Inspector's Tools tab
• ✅ Can successfully run git_context in MCP Inspector
• ✅ Cursor shows "1 tool" for house-rules server
• ✅ Assistant can call git_context and get results

Common Confusion

"Why can't I call house_rules as a tool?"

• Prompts are not tools. They're templates that the client applies to conversations.
• The client discovers prompts and uses them to set context, not as executable functions.

"How do I use the house_rules prompt then?"

• In Cursor, the client will discover and apply it automatically when relevant
• You can reference it in conversation: "Apply house_rules in review mode"
• The client retrieves the prompt and applies it to the conversation context

"How do I know if prompts are working?"

• Check that they're discoverable (appear in MCP Inspector and Cursor settings)
• The client applies them automatically - you'll notice the assistant following the rules
• Tools are easier to verify because you can call them directly and see results

Common Pitfalls

1. Logging to stdout breaks everything

Don't use console.log in a stdio MCP server. stdout is reserved for protocol messages. Always log to stderr using the provided log() function.

2. Use absolute paths

If you pass a relative path for repoPath, different clients may run your server with different working directories. Always use absolute paths to avoid weird failures.

3. Resist the urge to overbuild

It's tempting to add features like:

• "Summarize PR"
• "Open files"
• "Edit code"
• "Commit changes"

Resist it. This server is valuable because it stays focused:

• Publish reusable behavior (prompt)
• Publish reusable context (tool)

Everything else can remain in the AI client.

Customization

Modifying House Rules

Edit the prompt text in src/index.ts within the GetPromptRequestSchema handler. The rules are defined in the text array.

Adding New Modes

The mode parameter is already supported. You can extend the prompt logic to provide different instructions based on the mode:

const modeInstructions = {
  review: "Focus on code quality, potential bugs, and maintainability.",
  triage: "Prioritize issues by severity and impact.",
  "release-notes": "Generate concise, user-facing release notes.",
};

const text = [
  // ... existing rules ...
  modeInstructions[mode] || "",
].join("\n");

Extending Git Context

You can add more git information to the git_context tool by adding additional execFileAsync calls:

// Example: Get file changes
const fileChanges = await execFileAsync("git", [
  "-C",
  args.repoPath,
  "diff",
  "--name-status",
  "HEAD~1",
]).then((r) => r.stdout.trim());

Development

Build

npm run build

Run

npm start

TypeScript Configuration

The project uses strict TypeScript settings. See tsconfig.json for details.

License

MIT

Credits

This project is based on the article: "Stop Re-Explaining Yourself to AI with MCP" - a beginner-friendly guide to building reusable MCP servers.

Contributing

This is a minimal, focused server. If you want to extend it, consider:

1. Keeping it simple and focused
2. Adding only reusable prompts and context tools
3. Avoiding complex agent logic (that belongs in the client)

Remember: Tools are reusable actions. Prompts are reusable behavior. Together, they turn "I keep re-explaining myself" into "my client can discover how I work."