Skip to main content
Glama

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


Related MCP server: bragdoc-mcp

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)

Available Tools

7 tools
add_evidenceB

Add a new evidence or achievement and link it to the appraisal goals it fulfills

Inputs: goals (required), title (required), rubric (required), context (required), +4 more.

generate_game_planB

Generate an actionable game plan for completing remaining appraisal goals, with an accomplishments list for the supervisor and optional current initiatives section

Inputs: year, level, current_initiatives.

generate_reportA

Generate a full markdown report of evidences organized by rubric and goal, saved to Obsidian

Inputs: year, level.

generate_summaryA

Generate a mid-year appraisal summary note in English, Spanish, or both, saved to the Obsidian vault

Inputs: year, level, language.

get_appraisalB

Get all appraisal goals for a specific level

Inputs: level.

list_evidencesC

List all stored evidences with optional filters

Inputs: year, level, rubric.

update_evidence_imageB

Attach or replace the image of an existing evidence using the latest image in the Inbox folder

Inputs: evidence_id (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: generating different outputs (report, summary, game plan), managing evidences (add, list, update image), and retrieving appraisal goals. No two tools overlap in functionality.

    Naming Consistency5/5

    All tool names follow the verb_noun pattern consistently (e.g., generate_report, add_evidence, get_appraisal). The verbs are diverse but descriptive, and there is no mixing of naming conventions.

    Tool Count5/5

    With 7 tools, the server covers core workflows for an appraisal tracker without being bloated or insufficient. The number fits the domain well.

    Completeness3/5

    The tools cover adding and listing evidences, updating evidence images, and generating various reports. However, missing update/delete for evidences and any CRUD for appraisal goals (only get) leaves noticeable gaps for a complete lifecycle.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      D
      maintenance
      Enables AI assistants to search, read, create, and modify Markdown notes in local Obsidian vaults directly through filesystem operations. Supports tag-based discovery and frontmatter parsing without requiring Obsidian to be open, facilitating integration with VS Code Copilot via stdio transport.
      5
      13 npm
      4
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      Helps capture professional achievements using the STAR method through iterative interviews. Generates period summaries and performance review self-assessments.
      9
      10 npm
      -
    • A
      license
      A
      quality
      B
      maintenance
      Provides AI coding assistants persistent engineering memory stored as Markdown files in an Obsidian vault, enabling project context retrieval, session capture, decision recording, and memory search without requiring Obsidian to be running.
      7
      1
      MIT