# 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](https://github.com/nvm-sh/nvm)
- **VS Code** with the [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) extension
- **Obsidian** (optional but recommended — the vault is just a folder of Markdown files)

---

## Setup

### 1. Clone the repo

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

### 2. Install dependencies

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

### 3. Configure environment variables

Copy the example env file and edit it:

```bash
cp .env.example .env
```

Open `.env` and set your paths:

```env
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

```bash
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:

```bash
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):

```json
{
  "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:

```bash
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:

```json
{
  "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:

```env
DEFAULT_LEVEL=senior_consultant
```

And in `.vscode/mcp.json` under `env`:

```json
"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

```bash
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)