Appraisal Tracker MCP
Enables tracking professional achievements via natural language conversation in VS Code Copilot, using tools to log evidence, attach screenshots, and generate reports.
Stores evidence notes, reports, and summaries as structured Markdown files in an Obsidian vault, organized by year and appraisal level.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Appraisal Tracker MCP Log that I got my Azure AI Fundamentals certification today"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
| Save an achievement and link it to appraisal goals |
| Look up all goals for a level |
| List logged evidences with optional filters |
| Generate a full Markdown report organized by rubric and goal |
| Generate a mid-year summary note (English, Spanish, or both) |
| Generate a prioritized game plan for remaining goals |
| 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-mcp2. Install dependencies
node --version # make sure you're on v18+
npm install3. Configure environment variables
Copy the example env file and edit it:
cp .env.example .envOpen .env and set your paths:
OBSIDIAN_VAULT_PATH=/Users/yourname/Documents/YourVault
TRACKER_FOLDER=Appraisal Tracker
DEFAULT_LEVEL=lead_consultantOBSIDIAN_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 createdDEFAULT_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 build5. 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 206. Start the MCP server in VS Code
Open the Command Palette (
Cmd+Shift+P/Ctrl+Shift+P)Search for "MCP: List Servers"
Find
appraisal-trackerand click Start ServerOpen Copilot Chat, switch to Agent mode
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.mdHow 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:
levelmust match the filename exactly (e.g.,senior_consultant→senior_consultant.json)idinside each rubric must be one of:develop_business,develop_yourself,manage_business,support_customersGoal
idcan 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_consultantAnd 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 build4. 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 |
| Business development, mentoring, case studies, sales support |
| Certifications, learning, communication, technical growth |
| Compliance, utilization, processes, professional development |
| 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 toolsadd_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
Scored across 7 tools
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.
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.
With 7 tools, the server covers core workflows for an appraisal tracker without being bloated or insufficient. The number fits the domain well.
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
Related MCP Connectors
Notes and memory assistant: one Markdown vault that Claude, ChatGPT and any MCP client can share.
Connect AI assistants to your GitHub-hosted Obsidian vault to seamlessly access, search, and analy…
Privacy-first work tracking with summaries, reports, coaching, and AI-ready long-term memory.
Search and reason over your Obsidian-style Markdown vault, right from ChatGPT.
Related MCP Servers
- AlicenseCqualityDmaintenanceEnables 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.513 npm4MIT
- FlicenseAqualityDmaintenanceHelps capture professional achievements using the STAR method through iterative interviews. Generates period summaries and performance review self-assessments.910 npm-
- AlicenseAqualityBmaintenanceProvides 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.71MIT
- FlicenseBqualityCmaintenanceEnables developers to record feature-based development processes and turn Git changes, AI conversations, token usage, technical decisions, and debugging attempts into structured Obsidian learning reviews.10-