Skip to main content
Glama
ask-aayan

ask-aayan

README.md
# ask-aayan

[![CI](https://github.com/syedaayanahmed2001/ask-aayan/actions/workflows/ci.yml/badge.svg)](https://github.com/syedaayanahmed2001/ask-aayan/actions/workflows/ci.yml)

My CV is an MCP server. Ask your AI about me.

I'm Syed Aayan Ahmed, an AI & Automation Engineer. Add one line to Claude Code, Claude Desktop or
Cursor, then ask your own assistant "What has Aayan shipped with voice agents?", "Is he available
in March 2027?" or "How do I contact him?". It answers from tools that return only what is in my
CV and my portfolio.

<!-- demo gif goes here -->

## Connect

Remote endpoint (Streamable HTTP, read-only, no sign-in): `https://ask-aayan.vercel.app/mcp`

**Claude Code**

```sh
claude mcp add --transport http ask-aayan https://ask-aayan.vercel.app/mcp
```

**Claude Desktop**: Settings → Connectors → Add custom connector, and paste
`https://ask-aayan.vercel.app/mcp`. Or run it locally over stdio in `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "ask-aayan": {
      "command": "npx",
      "args": ["-y", "ask-aayan"]
    }
  }
}
```

**Cursor**: in `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "ask-aayan": {
      "url": "https://ask-aayan.vercel.app/mcp"
    }
  }
}
```

**Local stdio with Claude Code**

```sh
claude mcp add ask-aayan -- npx -y ask-aayan
```

The package is ready for npm but not published yet. Until it is, run it from a clone:

```sh
git clone https://github.com/syedaayanahmed2001/ask-aayan && cd ask-aayan
npm ci && npm run build
claude mcp add ask-aayan -- node "$PWD/dist/cli.js"
```

## Example questions

Real output from a local run (`npm run demo`): the question, the tool call a client makes for it,
and what the server returns.

<!-- examples:start -->
**"What has Aayan shipped with voice agents?"** → `get_projects({"tag":"voice"})`

```text
1 project(s) tagged "voice":

Bautagesbericht Pro — Production · Teamworks AI
  A construction-site PWA with voice input for every field, in any language.
  Workers speak a field, like the day's progress or the materials, in their own language. Whisper transcribes it, the app fills the field and adds a German translation, and the German text is post-processed into formal, legally compliant German for the official daily report. No signal on site? Everything saves locally and syncs once the signal comes back, and every entry carries a unique ID, so nothing is lost or duplicated. Seven languages, including Arabic right to left, and three roles (entry, approval, analytics) with permissions enforced in the database. Reports can also be started with a phone call; the AI puts a draft straight into the app.
  - Lead front-end engineer; ~15k lines of TypeScript, 7 languages including RTL Arabic, 3 user roles enforced with row-level security.
  - Voice-AI reporting channel: foremen talk to a fonio.ai phone agent, and an Edge Function turns the call transcript into a draft report using OpenAI JSON-schema extraction, which a foreman then approves (human-in-the-loop). This cut end-of-day reporting from ~15 to 4–6 minutes.
  Role: Lead front-end engineer
  Result: Any language → formal German report
  Stack: React, TypeScript, Tailwind, Supabase/PostgreSQL, Edge Functions, IndexedDB, Whisper, fonio.ai, OpenAI JSON-schema extraction
  Tags: voice, voice-agent, extraction, llm, human-in-the-loop, pwa, offline-first, full-stack, i18n, production
  Source: portfolio content/work.ts bautagesbericht-pro; CV en.experience[1].bullets[0-1]
```

**"Is he available in March 2027?"** → `get_availability({"date":"2027-03"})`

```text
03/2027: yes. His profile says he is available full-time from 03/2027, after graduating.

Now: Working student, AI Engineering at Teamworks AI, since 08/2026 (before that: Intern, Software Development & AI Automation at Teamworks AI, 11/2025 – 05/2026).
Graduating: B.Sc. Computer Science & Artificial Intelligence, Technische Hochschule Ingolstadt (THI), 02/2027.
Full-time from: 03/2027.
Looking for: A full-time role as a Junior AI, Automation or Forward Deployed Engineer.
Location: Augsburg · Ingolstadt.

Source: owner brief (availability); CV en.experience[0-1] dates, en.education[0], en.profile; portfolio content/chapters.ts storyNext
```

**"How do I contact him?"** → `get_contact({})`

```text
Email: syedaayan2001@gmail.com
LinkedIn: https://www.linkedin.com/in/syedaayanahmed
GitHub: https://github.com/syedaayanahmed2001
Portfolio: https://aayanahmedportfolio.vercel.app
CV (PDF): https://aayanahmedportfolio.vercel.app/aayan-ahmed-cv.pdf
Location: Augsburg · Ingolstadt

To set up a call, use book_call.
Source: CV contact.email, contact.linkedin; GitHub and CV PDF URL from owner brief; portfolio content/site.ts siteUrl, location
```
<!-- examples:end -->

## Reference

### Tools

All tools are read-only. Inputs are validated with zod; invalid input comes back as an error
result and never reaches the handler. Every tool returns text plus the same answer as structured
content.

| Tool | Input | Returns |
|---|---|---|
| `get_summary` | `lang?`: `en` \| `de` | Headline, target role, location, current job, profile, languages, his one belief about the work |
| `get_experience` | `company?`, `skill?`, `lang?` | Jobs, newest first, with dates and what he built. No match → empty list and the valid companies |
| `get_projects` | `tag?` (e.g. `voice`, `extraction`, `on-prem`) | Projects with role, results and stack. Unknown tag → the list of tags |
| `search_profile` | `query` (2–200 chars), `limit?` (1–25, default 8) | Ranked snippets, each labelled with its section and title |
| `get_skills` | `group?`, `lang?` | Skill groups as on the CV, plus spoken languages |
| `get_availability` | `date?` (`YYYY-MM`) | Current role, graduation (02/2027), full-time from 03/2027; yes/no for a given month |
| `get_contact` | none | Email, LinkedIn, GitHub, portfolio, CV PDF, location |
| `book_call` | `topic?`, `company?` | The `BOOKING_URL` scheduling link if set, else a `mailto:` link with the subject filled in |

### Resources

| URI | Content |
|---|---|
| `aayan://cv/en` | Full CV in English, Markdown |
| `aayan://cv/de` | Full CV in German, Markdown |

### Prompt

`screen-candidate(job_description)`: asks the model for a structured screening (fit summary,
evidence per requirement, gaps, questions to ask) that uses only this server's tool results and
marks anything else "not in profile".

## How facts are sourced

Every fact lives in one file, [`src/profile.ts`](src/profile.ts). Each section and each list item
has a `source` note naming where it was copied from: my CV (English and German), the public copy
of [my portfolio](https://aayanahmedportfolio.vercel.app), or my own decisions about how things
are worded. A zod schema checks the file at startup: no empty strings, no missing `source`, no
unknown fields.

Left out on purpose: phone number, street address, postal code, date of birth, client names, and
anything I have not confirmed. Tests run the profile, every tool's output, both resources, the
prompt, the landing page and these docs through a deny-list and fail on a match. The deny-list
checks shapes (any phone number, a postal code, a full date, any GitHub account but mine), so the
private values themselves never have to be written into this public repo. Names that must not be
published sit in an untracked `.denylist.local` that the same tests read when it exists.

The server never calls an LLM. It is a lookup over that file; your assistant does the talking, and
the server's instructions tell it to answer only from tool results.

## How it works

```mermaid
flowchart LR
  subgraph Clients
    CC[Claude Code]
    CD[Claude Desktop]
    CU[Cursor]
  end
  CC -- "stdio: npx ask-aayan" --> CLI[src/cli.ts<br/>StdioServerTransport]
  CD -- stdio --> CLI
  CC -- "HTTP: /mcp" --> API[api/mcp.js on Vercel<br/>WebStandardStreamableHTTPServerTransport<br/>stateless, JSON]
  CD -- HTTP --> API
  CU -- HTTP --> API
  CLI --> S[createServer<br/>8 tools · 2 resources · 1 prompt]
  API --> S
  S --> H[handlers.ts<br/>pure functions]
  H --> P[(profile.ts<br/>zod-validated facts<br/>source per item)]
```

The HTTP endpoint uses the official SDK's Web-standard transport inside a plain Vercel Function
(`export default { fetch }`), so there is no framework. Each request gets a fresh server, which
suits read-only tools on serverless.

## How this was built: spec first

I wrote the spec before the code, in three phases (data and tool logic, MCP server and stdio,
HTTP endpoint and docs), and committed each one as "spec" first and "implementation" second. Every
requirement has an ID, and every test title starts with the ID it proves, for example
`TOOL-06: March 2027 and later is yes`. The spec is in [docs/SPEC.md](docs/SPEC.md).

## Development

Requires Node 22 or newer.

```sh
npm ci
npm test            # vitest
npm run typecheck
npm run lint
npm run build       # src/ → dist/
npm run dev:http    # landing page and endpoint on http://127.0.0.1:3210 (PORT to change)
npm run demo        # prints the example section above from a live local run
```

Try it with the MCP Inspector while `npm run dev:http` is running:

```sh
npx @modelcontextprotocol/inspector --cli http://127.0.0.1:3210/mcp --transport http --method tools/list
```

To change what the server says, edit `src/profile.ts` and run the tests. To return a scheduling
link from `book_call`, set `BOOKING_URL` to an `https:` URL (locally or as a Vercel environment
variable).

Deploying: import the repository in Vercel. `vercel.json` runs `npm run build`, serves `public/`
(the landing page) and routes `/mcp` to the function in `api/mcp.js`. No environment variables
are required.

## License

MIT © Syed Aayan Ahmed. See [LICENSE](LICENSE).

TDQS

A3.9/5.0

Scored across 8 tools

Disambiguation4/5

Each tool maps to a distinct profile section (summary, experience, projects, skills, availability, contact, scheduling), so selection is mostly obvious. The only soft overlap is search_profile, which spans all sections, but it is explicitly framed as the fallback for specifics the targeted tools do not cover.

Naming Consistency5/5

All eight tools follow a clean verb_noun snake_case pattern (get_summary, get_experience, search_profile, book_call). The verb varies (get/search/book) but the convention is uniform and predictable.

Tool Count5/5

Eight tools is well within the sweet spot for a personal-profile server, and each one covers a distinct section or action with no filler. Nothing feels padded or missing at the count level.

Completeness4/5

The surface covers the full lifecycle of a profile query: overview, experience, projects, skills, availability, contact, scheduling, plus keyword search as a catch-all. Education and lab demos are only reachable via search_profile, a minor gap an agent can work around.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues