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

Tool	What it does
add_evidence	Save an achievement and link it to appraisal goals
get_appraisal	Look up all goals for a level
list_evidences	List logged evidences with optional filters
generate_report	Generate a full Markdown report organized by rubric and goal
generate_summary	Generate a mid-year summary note (English, Spanish, or both)
generate_game_plan	Generate a prioritized game plan for remaining goals
update_evidence_image	Attach or add an image to an existing evidence note

---

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:

Rubric	Description
develop_business	Business development, mentoring, case studies, sales support
develop_yourself	Certifications, learning, communication, technical growth
manage_business	Compliance, utilization, processes, professional development
support_customers	Delivery quality, client relationships, team support

---

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)