@cben0ist/ascend-mcp-server 1.0.1

package/.env.example

@@ -0,0 +1,10 @@
+# Ascend MCP Server Configuration
+# Copy this file to .env and fill in your values
+
+# Your Ascend API base URL for MCP endpoints
+# Production: https://ascend.workingensemble.ca/api/mcp
+# Local dev:  http://localhost:4000/api/mcp
+ASCEND_API_URL=https://ascend.workingensemble.ca/api/mcp
+
+# Your Ascend API key (get from Settings → Claude AI Integration)
+ASCEND_API_KEY=your_64_char_hex_key_here

package/README.md

@@ -0,0 +1,87 @@
+# Ascend MCP Server
+
+Connect Claude (Desktop, Code, or agents) to your Ascend job search data.
+
+## What it does
+
+Gives Claude read-only access to:
+- **Job applications** — list, filter by status, get full details with AI analysis
+- **Resume** — your base resume in JSON Resume format
+- **Dashboard stats** — totals, interview counts, match scores
+- **Analytics** — trends and period-over-period comparisons
+
+## Setup
+
+### 1. Get your API key
+
+1. Open Ascend → Settings → **Claude AI Integration**
+2. Click **Generate Key** and copy the key (shown once)
+
+### 2. Install dependencies
+
+```bash
+cd mcp
+npm install
+```
+
+### 3. Configure Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "ascend": {
+      "command": "node",
+      "args": ["/absolute/path/to/ascend/mcp/src/index.js"],
+      "env": {
+        "ASCEND_API_URL": "https://ascend.workingensemble.ca/api/mcp",
+        "ASCEND_API_KEY": "your_key_here"
+      }
+    }
+  }
+}
+```
+
+### 4. Configure Claude Code
+
+```bash
+claude mcp add ascend \
+  -e ASCEND_API_URL=https://ascend.workingensemble.ca/api/mcp \
+  -e ASCEND_API_KEY=your_key_here \
+  -- node /absolute/path/to/ascend/mcp/src/index.js
+```
+
+### Local development
+
+```bash
+ASCEND_API_URL=http://localhost:4000/api/mcp \
+ASCEND_API_KEY=your_key_here \
+node mcp/src/index.js
+```
+
+### Test with MCP Inspector
+
+```bash
+cd mcp
+ASCEND_API_URL=http://localhost:4000/api/mcp ASCEND_API_KEY=your_key \
+  npx @modelcontextprotocol/inspector node src/index.js
+```
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_applications` | List applications with optional status filter |
+| `get_application` | Full details for one application including AI analysis |
+| `get_resume` | Your base resume in JSON Resume format |
+| `get_dashboard_stats` | Total applications, interviews, offers, avg match score |
+| `get_analytics_overview` | Trends and analytics for a date range |
+
+## Example prompts
+
+- "How many job applications do I have in total?"
+- "Show me applications where I'm currently interviewing"
+- "What's my average job match score?"
+- "Summarize my resume"
+- "How has my application rate changed over the last month?"

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@cben0ist/ascend-mcp-server",
+  "version": "1.0.1",
+  "description": "MCP server for Ascend — connect Claude to your job applications, resume, and analytics",
+  "type": "module",
+  "bin": {
+    "ascend-mcp": "src/index.js"
+  },
+  "scripts": {
+    "start": "node src/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "axios": "^1.7.0",
+    "zod": "^3.22.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/client.js

@@ -0,0 +1,34 @@
+import axios from 'axios';
+
+/**
+ * Create an Ascend API client authenticated with the given API key.
+ * @param {string} baseURL - e.g. http://localhost:4000/api/mcp
+ * @param {string} apiKey  - 64-char hex API key
+ */
+export function createClient(baseURL, apiKey) {
+  const client = axios.create({
+    baseURL,
+    headers: {
+      'Authorization': `Bearer ${apiKey}`,
+      'Content-Type': 'application/json',
+    },
+    timeout: 30000,
+  });
+
+  // Normalize errors for MCP tools
+  client.interceptors.response.use(
+    (response) => response,
+    (error) => {
+      const message = error.response?.data?.error
+        || error.response?.data?.message
+        || error.message
+        || 'Unknown error';
+      const status = error.response?.status || 0;
+      const normalized = new Error(`Ascend API error (${status}): ${message}`);
+      normalized.status = status;
+      return Promise.reject(normalized);
+    }
+  );
+
+  return client;
+}

package/src/index.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createClient } from './client.js';
+import { registerAllTools } from './tools/index.js';
+
+const ASCEND_API_URL = process.env.ASCEND_API_URL;
+const ASCEND_API_KEY = process.env.ASCEND_API_KEY;
+
+if (!ASCEND_API_URL) {
+  console.error('Error: ASCEND_API_URL environment variable is required');
+  console.error('Example: ASCEND_API_URL=https://ascend.workingensemble.ca/api/mcp');
+  process.exit(1);
+}
+
+if (!ASCEND_API_KEY) {
+  console.error('Error: ASCEND_API_KEY environment variable is required');
+  console.error('Get your API key from Settings → Claude AI Integration in the Ascend app');
+  process.exit(1);
+}
+
+const client = createClient(ASCEND_API_URL, ASCEND_API_KEY);
+
+const server = new McpServer({
+  name: 'ascend',
+  version: '1.0.0',
+});
+
+registerAllTools(server, client);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error('Ascend MCP server running on stdio');

package/src/tools/analytics.js

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+
+export function registerAnalyticsTools(server, client) {
+  server.tool(
+    'get_analytics_overview',
+    'Get analytics overview: application trends, interview rates, offer rates, and period-over-period comparisons.',
+    {
+      startDate: z.string().optional().describe('Start date ISO8601 (default: 30 days ago)'),
+      endDate: z.string().optional().describe('End date ISO8601 (default: today)'),
+    },
+    async ({ startDate, endDate }) => {
+      try {
+        const params = {};
+        if (startDate) params.startDate = startDate;
+        if (endDate) params.endDate = endDate;
+        const { data } = await client.get('/analytics', { params });
+        return {
+          content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: 'text', text: err.message }],
+          isError: true,
+        };
+      }
+    }
+  );
+}

package/src/tools/applications.js

@@ -0,0 +1,49 @@
+import { z } from 'zod';
+
+export function registerApplicationTools(server, client) {
+  server.tool(
+    'list_applications',
+    'List job applications from Ascend. Returns a paginated list with status, company, job title, and match score.',
+    {
+      status: z.string().optional().describe('Filter by status (e.g. applied, interviewing, offer, rejected)'),
+      limit: z.number().int().min(1).max(100).optional().default(20).describe('Number of results (default 20, max 100)'),
+      offset: z.number().int().min(0).optional().default(0).describe('Pagination offset'),
+    },
+    async ({ status, limit, offset }) => {
+      try {
+        const params = { limit, offset };
+        if (status) params.status = status;
+        const { data } = await client.get('/applications', { params });
+        return {
+          content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: 'text', text: err.message }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    'get_application',
+    'Get full details for a specific job application including AI analysis, tailored resume, and metadata.',
+    {
+      id: z.string().describe('Application ID (UUID)'),
+    },
+    async ({ id }) => {
+      try {
+        const { data } = await client.get(`/applications/${encodeURIComponent(id)}`);
+        return {
+          content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: 'text', text: err.message }],
+          isError: true,
+        };
+      }
+    }
+  );
+}

package/src/tools/index.js

@@ -0,0 +1,11 @@
+import { registerApplicationTools } from './applications.js';
+import { registerResumeTools } from './resume.js';
+import { registerStatsTools } from './stats.js';
+import { registerAnalyticsTools } from './analytics.js';
+
+export function registerAllTools(server, client) {
+  registerApplicationTools(server, client);
+  registerResumeTools(server, client);
+  registerStatsTools(server, client);
+  registerAnalyticsTools(server, client);
+}

package/src/tools/resume.js

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+
+export function registerResumeTools(server, client) {
+  server.tool(
+    'get_resume',
+    'Get the user\'s base resume in JSON Resume format. Includes work history, education, skills, projects, and contact info.',
+    {},
+    async () => {
+      try {
+        const { data } = await client.get('/resume');
+        return {
+          content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: 'text', text: err.message }],
+          isError: true,
+        };
+      }
+    }
+  );
+}

package/src/tools/stats.js

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+
+export function registerStatsTools(server, client) {
+  server.tool(
+    'get_dashboard_stats',
+    'Get dashboard statistics: total applications, active applications, interviews, offers, and average AI match score.',
+    {},
+    async () => {
+      try {
+        const { data } = await client.get('/stats');
+        return {
+          content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: 'text', text: err.message }],
+          isError: true,
+        };
+      }
+    }
+  );
+}