Appraisal Tracker MCP

A local MCP (Model Context Protocol) server that connects to VS Code Copilot and helps you track your annual performance appraisal by logging evidence directly into an Obsidian vault — using natural language conversation.

Instead of manually filling spreadsheets or forgetting what you accomplished, you just tell Copilot what you did and it handles the rest: asks follow-up questions, maps the achievement to your appraisal goals, attaches screenshots, and writes structured Markdown notes to your vault.

What it does

• Log professional achievements conversationally — no forms, no structure needed

• Automatically maps evidence to appraisal goals by rubric

• Attaches screenshots or images to evidence notes

• Lists all logged evidences with filters

• Generates a full appraisal evidence report

• Generates a mid-year summary note (English, Spanish, or both)

• Generates an actionable game plan for completing remaining goals

Tools available

Requirements

• Node.js v18+ — recommended to use nvm

• VS Code with the GitHub Copilot extension

• Obsidian (optional but recommended — the vault is just a folder of Markdown files)

Setup

1. Clone the repo

git clone https://github.com/your-username/appraisal-tracker-mcp.git
cd appraisal-tracker-mcp

2. Install dependencies

node --version  # make sure you're on v18+
npm install

3. Configure environment variables

Copy the example env file and edit it:

cp .env.example .env

Open .env and set your paths:

OBSIDIAN_VAULT_PATH=/Users/yourname/Documents/YourVault
TRACKER_FOLDER=Appraisal Tracker
DEFAULT_LEVEL=lead_consultant

• OBSIDIAN_VAULT_PATH — the root folder of your Obsidian vault (or any folder where you want the notes saved)

• TRACKER_FOLDER — the subfolder inside the vault where all tracker files will be created

• DEFAULT_LEVEL — your appraisal level. The server uses this automatically so you never have to specify it in conversation. Change it to match your level (e.g., senior_consultant, principal_consultant)

4. Build the project

node --version          # confirm Node 18+
npm run build           # compiles TypeScript to dist/

If you're using nvm and the wrong Node version is active, run:

nvm use 20
npm run build

5. Configure VS Code Copilot

Create a .vscode/mcp.json file in this project (or in any workspace you want to use the tracker from):

{
  "servers": {
    "appraisal-tracker": {
      "type": "stdio",
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/appraisal-tracker-mcp/dist/index.js"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/Users/yourname/Documents/YourVault",
        "TRACKER_FOLDER": "Appraisal Tracker",
        "DEFAULT_LEVEL": "lead_consultant"
      }
    }
  }
}

Important: Use the absolute path to your Node binary — ${workspaceFolder} does not work here.

To find your Node path:

which node
# or if using nvm:
nvm which 20

6. Start the MCP server in VS Code

1. Open the Command Palette (Cmd+Shift+P / Ctrl+Shift+P)

2. Search for "MCP: List Servers"

3. Find appraisal-tracker and click Start Server

4. Open Copilot Chat, switch to Agent mode

5. You should see the tools listed — you're ready to go

Folder structure created in your vault

YourVault/
└── Appraisal Tracker/
    ├── attachments/          ← screenshots and images go here
    ├── evidences/
    │   └── 2026/
    │       └── lead_consultant/
    │           ├── ev_20260427_001.md
    │           └── ev_20260518_001.md
    ├── reports/              ← generated by generate_report
    ├── 2026 Mid-Year Summary.md
    ├── 2026 Resumen Mid-Year.md
    └── 2026 Game Plan.md

How to use it

Open Copilot in Agent mode and just talk to it naturally:

Logging an achievement:

"I got my Azure AI Fundamentals certification today"

Copilot will ask follow-up questions (date, people involved, outcome, do you have a screenshot?) and then save the evidence note automatically.

Attaching a screenshot:

Save your screenshot to YourVault/Appraisal Tracker/attachments/ first, then tell Copilot: "Add the latest screenshot to that evidence"

Generating a summary:

"Generate my mid-year summary in both English and Spanish"

Generating a game plan:

"Generate my game plan. I'm currently working on: a dashboard for banking users, a skill meter tool, and studying for the AI-102 certification"

Listing what you've logged:

"Show me all my evidences for this year"

Adding support for other appraisal levels

Currently includes goals for lead_consultant. To add another level (e.g., Senior Consultant, Principal, etc.):

1. Create the appraisal JSON file

Add a new file at src/data/appraisals/senior_consultant.json (use lowercase and underscores for the filename).

The file must follow this structure:

{
  "level": "senior_consultant",
  "displayName": "Senior Consultant",
  "rubrics": [
    {
      "id": "develop_business",
      "name": "Develop your business",
      "goals": [
        {
          "id": 1,
          "description": "Description of goal 1 exactly as it appears in the appraisal rubric"
        },
        {
          "id": 2,
          "description": "Description of goal 2"
        }
      ]
    },
    {
      "id": "develop_yourself",
      "name": "Develop yourself",
      "goals": [
        {
          "id": 7,
          "description": "Obtain a technical certification aligned to your technology stack"
        }
      ]
    },
    {
      "id": "manage_business",
      "name": "Manage your business",
      "goals": []
    },
    {
      "id": "support_customers",
      "name": "Support your customers",
      "goals": []
    }
  ]
}

Rules:

• level must match the filename exactly (e.g., senior_consultant → senior_consultant.json)

• id inside each rubric must be one of: develop_business, develop_yourself, manage_business, support_customers

• Goal id can be a number (1, 2) or a string for sub-goals ("6a", "6b")

• Copy the goal descriptions directly from the official appraisal document so they match exactly

2. Set your level in .env and mcp.json

Update DEFAULT_LEVEL in your .env file:

DEFAULT_LEVEL=senior_consultant

And in .vscode/mcp.json under env:

"DEFAULT_LEVEL": "senior_consultant"

This is the level the server will use automatically — you never have to specify it in conversation.

3. Rebuild the project

npm run build

4. Restart the MCP server in VS Code

Open MCP: List Servers from the Command Palette and restart appraisal-tracker.

4. Use it

Now you can tell Copilot:

"Add evidence for level senior_consultant — I led a client demo today"

Or generate a summary for that level:

"Generate my mid-year summary for senior_consultant"

You can have multiple levels active at the same time — each one stores its evidences in its own subfolder inside the vault (evidences/2026/senior_consultant/).

Appraisal goal structure

Goals are organized in 4 rubrics:

Customizing Copilot behavior

The file .github/copilot-instructions.md controls how Copilot behaves as an agent — what questions it asks before saving evidence, the tone it uses, and how it maps goals.

Edit this file to adjust the behavior for your workflow.

Tech stack

• TypeScript + Node.js

• @modelcontextprotocol/sdk — MCP server implementation

• zod — input validation

• dotenv — environment configuration

• Plain Markdown files as storage (no database)