{
  "markdown": "# ask-me-mcp\n\nA persona MCP server. Ask Claude / ChatGPT / Grok about the operator's work, patterns, availability, and offer — grounded in their public résumé, projects index, and offer page.\n\n> **Reference implementation of the MCP-Server Harness pattern.** This repo is a working example of the same architecture the operator sells as a productized 6-week engagement. If you like the shape, that's the sales pitch — see [The pattern](#the-pattern-the-mcp-server-harness) at the bottom.\n\n## What it does\n\nSix typed tools any AI-assistant user can call:\n\n| Tool | What it returns |\n|---|---|\n| `get_current_focus` | Current allocation, active engagements, and the primary vertical wedge in progress. |\n| `get_engagement_summary` | A specific engagement (NXT Robotics, AIMIA, Hydrostasis, Digital QR Card) described at a public-safe level. |\n| `search_reusable_patterns` | Keyword search over the operator's 12+ reusable engineering-patterns catalog. |\n| `check_availability` | How many Playbook / Retainer slots are open + earliest next-open date. |\n| `get_offer_details` | Current bundled offer: MCP-Server Playbook + Fractional CTO Retainer. |\n| `book_discovery_call` | Instructions + prep guidance for booking a discovery call. **Does not auto-schedule. Explicitly refuses to negotiate price.** |\n\nEvery response ships with a confidence label and a source citation. The server never invents; if the grounding data doesn't say it, the server doesn't say it.\n\n## Install (as a user)\n\nThe remote endpoint speaks MCP Streamable HTTP + OAuth 2.1. Three ways to connect:\n\n### 1. Claude Desktop — connector directory (\"Connect\" button)\n\nAdd via the Claude Desktop UI: **Settings → Connectors → Add custom connector → URL: `https://ask-me-mcp-xi.vercel.app/api/mcp`**. Click **Connect**. The desktop client discovers OAuth metadata, registers as a client, exchanges tokens, and mounts the tools. No manual config.\n\n### 2. Claude Desktop / Claude Code — config file (skip OAuth)\n\nAdd to `claude_desktop_config.json` — location varies by OS; see [Claude Desktop config docs](https://modelcontextprotocol.io/quickstart/user):\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"ask-me\": {\n      \"url\": \"https://ask-me-mcp-xi.vercel.app/api/mcp\"\n    }\n  }\n}\n```\n\n### 3. Claude Code CLI\n\n```bash\nclaude mcp add --scope user ask-me https://ask-me-mcp-xi.vercel.app/api/mcp\n```\n\n### Local stdio (development)\n\nFor local stdio dev (no HTTP, no OAuth — auth doesn't apply to stdio):\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"ask-me\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/ask-me-mcp/dist/src/server.js\"]\n    }\n  }\n}\n```\n\nThen in any Claude Code session:\n\n> what's Ilyes's current focus?\n> what patterns has he shipped for LLM evaluation?\n> is he available for a Playbook engagement in October?\n\n## Develop (as a maintainer)\n\n### Requirements\n\n- Node.js 20+\n- npm (or pnpm / yarn — package.json is npm-first)\n\n### Setup\n\n```bash\ngit clone https://github.com/tounsils/ask-me-mcp.git\ncd ask-me-mcp\nnpm install\n```\n\n### Run locally as a stdio server\n\n```bash\nnpm run dev\n```\n\nPoint Claude Code or the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) at the resulting process.\n\n### Build for production\n\n```bash\nnpm run build\n```\n\nOutputs to `dist/`.\n\n### Deploy to Vercel\n\n```bash\n# Set the JWT signing secret (one-time; required for OAuth).\nvercel env add MCP_JWT_SECRET production\n# Paste a long random string. Generate one: `openssl rand -base64 48`.\n\nvercel deploy --prod\n```\n\nThe `api/mcp.ts` handler serves the [Streamable HTTP transport](https://modelcontextprotocol.io/docs/concepts/transports) with OAuth 2.1 protection — the format Claude's connector directory and ChatGPT's Apps SDK both use. See [`docs/oauth-flow.md`](docs/oauth-flow.md) for the full architecture.\n\n### Run the eval corpus\n\n```bash\nnpm run eval           # 15 tool cases against handlers directly (no HTTP)\nnpm run eval:oauth     # 6-step end-to-end OAuth flow (needs MCP_JWT_SECRET)\n```\n\nThe tool corpus fails the build if fewer than a threshold percentage of expected answers match. **Pass or nothing ships.**\n\nThe OAuth flow test exercises register → authorize → token → protected /api/mcp → 401 challenge → refresh — all in-process against Vercel-shaped mock req/res objects.\n\n## Repository layout\n\n```\nask-me-mcp/\n├── src/\n│   ├── server.ts               # shared MCP server (used by both stdio + HTTP)\n│   ├── tools/                  # six typed tool implementations\n│   │   ├── getCurrentFocus.ts\n│   │   ├── getEngagementSummary.ts\n│   │   ├── searchReusablePatterns.ts\n│   │   ├── checkAvailability.ts\n│   │   ├── getOfferDetails.ts\n│   │   └── bookDiscoveryCall.ts\n│   ├── grounding/\n│   │   ├── data.json           # pre-extracted structured facts (v0)\n│   │   └── index.ts            # loaders + search helpers\n│   └── rails/\n│       └── confidence.ts       # confidence + source-citation wrapper; refusal helper\n│   └── oauth/                  # OAuth 2.1 + PKCE + anonymous DCR\n│       ├── config.ts           # issuer, scopes, TTLs, endpoint paths\n│       ├── jwt.ts              # HS256 sign/verify (via `jose`)\n│       ├── clientRegistry.ts   # client_id = signed JWT (no DB)\n│       └── codeGrant.ts        # auth code + access/refresh token + PKCE S256\n├── api/\n│   ├── mcp.ts                          # Vercel serverless entry (Streamable HTTP + Bearer auth)\n│   ├── health.ts                       # diagnostic (unauthenticated)\n│   ├── register.ts                     # RFC 7591 DCR\n│   ├── authorize.ts                    # authorization endpoint (auto-approves)\n│   ├── token.ts                        # token exchange with PKCE\n│   ├── oauth-protected-resource.ts     # RFC 9728 metadata\n│   └── oauth-authorization-server.ts   # RFC 8414 metadata\n├── eval/\n│   ├── corpus.json             # 15 tool cases + expected answers\n│   ├── runner.ts               # replays tool corpus, threshold-gated\n│   └── oauth-flow.ts           # 6-step OAuth end-to-end test\n├── docs/\n│   └── oauth-flow.md           # OAuth architecture + how to swap for real user identity\n├── package.json\n├── tsconfig.json\n├── vercel.json\n└── README.md\n```\n\n## The pattern: the MCP-Server Harness\n\nThis project is a reference implementation of a pattern the operator ships to clients as a productized 6-week engagement — the **MCP-Server Product Playbook**.\n\nThe shape:\n\n1. **Typed tool contract.** Six JSON-schema-strict tools. Nothing free-form. The model can only invoke these, only with these arguments.\n2. **Coordinator + specialists (extensible).** v0 has one coordinator (the MCP server routing tool calls). v1 will add elicitation + supervisor agents inside more complex tools.\n3. **Typed signal vector.** Structured facts extracted from the grounding data. Not free-text.\n4. **Versioned reasoning specification.** The tool implementations ARE the reasoning spec — versioned in the code, not in a prompt.\n5. **Rails + confidence.** Every response carries `confidence` + `sources` + optional `disclaimers`. The model can display them.\n6. **External grounding.** The server queries `src/grounding/data.json`; the model never invents.\n7. **Evaluation corpus + eval runner + certification.** `eval/corpus.json` has expected answers; `npm run eval` replays them. Ships or doesn't.\n\nIf you're building a product that fits this shape (career guidance, medical triage, legal intake, financial planning, coaching, expert-system anything), the operator sells a 6-week fixed-scope engagement to ship it. See [`get_offer_details`](src/tools/getOfferDetails.ts) or email `tounsils@gmail.com`.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n\n## Attribution\n\nBuilt by [Ilyes Tounsi](https://linkedin.com/in/mohameditounsi) · Carlsbad, CA · [tounsils.github.io](https://tounsils.github.io).\n",
  "bytes": 7753,
  "sha": "4c8b482789af55c1f13d4fc2f59c032625746560f3eeb3d10e4ed18d3b9faba4",
  "repo_slug": "tounsils/ask-me-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_tounsils_ask_me_mcp_b134fba1/readme"
}