{
  "markdown": "<p align=\"center\">\n<a href=\"https://paladini.io/harness-score/guide/maturity-model#l1-%C2%B7-documented\" title=\"Harness Score — AI coding harness maturity\"><img alt=\"Harness Score L1 (Documented): measures AI-assisted development harness maturity with harness-score\" src=\"https://paladini.github.io/harness-score/maturity/badge-l1.svg\" height=\"20\"></a>\n  <img src=\"docs/assets/og-image.svg\" alt=\"mcp-me — Your Digital Identity Layer for AI\" width=\"100%\">\n</p>\n\n# mcp-me\n\n**Your AI assistants don't know who you are.** Every time you start a conversation with Claude, Copilot, Cursor, or Windsurf, it's a blank slate — no context about your skills, your projects, your career, or what you care about.\n\n**mcp-me fixes that.** It creates a structured personal profile that any AI assistant can read via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/). Think of it as a **digital identity layer for AI** — your bio, career, skills, interests, projects, and more, always available to every AI tool you use.\n\n```\nYou: \"Write me a cover letter for this job\"\nAI:  (reads your me://career, me://skills, me://projects)\n     \"Based on your 5 years at Acme Corp, your TypeScript expertise,\n      and your open-source work on mcp-me...\"\n```\n\n## Why mcp-me?\n\n- **AI that knows you** — Your assistants remember your skills, career, projects, and personality across every conversation\n- **Auto-generated** — Pull data from 329 registered generators (implemented across 44 generator source files) with one command\n- **Privacy-first** — All data stays local in YAML files on your machine. Nothing is sent to any cloud.\n- **Real-time plugins** — 13 live integrations (Spotify now playing, GitHub repos, Last.fm scrobbles) that AI queries on demand\n- **Extensible** — Community-driven generators and plugins. Add a new data source in ~10 lines of code.\n- **Works everywhere** — Claude Desktop, Cursor, Windsurf, Copilot, and any MCP-compatible AI assistant\n\n## Installation\n\n> **Prerequisite:** [Node.js](https://nodejs.org/) 20 or later. Verify with `node -v`.\n\n### One-Click Install\n\nAdd mcp-me to your AI assistant in one click — no path configuration needed (profile defaults to `~/.mcp-me`):\n\n<p align=\"center\">\n  <a href=\"https://cursor.com/install-mcp?name=me&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm1jcC1tZSIsInNlcnZlIl19\">\n    <img src=\"https://cursor.com/deeplink/mcp-install-dark.svg\" alt=\"Add mcp-me to Cursor\" height=\"32\">\n  </a>\n  &nbsp;&nbsp;\n  <a href=\"vscode:mcp/install?%7B%22name%22%3A%22me%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22mcp-me%22%2C%22serve%22%5D%7D\">\n    <img src=\"https://img.shields.io/badge/VS_Code-Install_MCP-007ACC?style=for-the-badge&logo=visualstudiocode\" alt=\"Install mcp-me in VS Code\" height=\"32\">\n  </a>\n</p>\n\n**Claude Desktop:** Download the [latest `.mcpb` release](https://github.com/paladini/mcp-me/releases/latest) and double-click to install, or drag it into Claude Desktop → Settings → Extensions.\n\nAfter installing, initialize your profile:\n\n```bash\nmcp-me init\nmcp-me generate --github your-username\n```\n\n### npm (recommended)\n\n```bash\nnpm install -g mcp-me\n```\n\nThis makes the `mcp-me` command available everywhere on your system. No need to clone any repository — npm downloads the package for you.\n\n```bash\nmcp-me --help\nmcp-me init\nmcp-me generate --github your-username\nmcp-me serve\n```\n\n**Alternative — run without installing** (via `npx`):\n\n```bash\nnpx mcp-me --help\n```\n\n`npx` downloads the package temporarily and runs it. Useful for trying mcp-me once, but slower on repeated use since it re-downloads each time.\n\n> **Profile location:** Commands default to `~/.mcp-me`. Override with `MCP_ME_PROFILE_DIR` or pass an explicit path: `mcp-me serve ~/my-profile`.\n\n## Quick Start\n\n```bash\n# 1. Initialize your profile (creates YAML templates + .mcp-me.yaml in ~/.mcp-me)\nmcp-me init\n\n# 2. Edit the config file — uncomment your sources\ncode ~/.mcp-me/.mcp-me.yaml\n```\n\nYour `.mcp-me.yaml` config file:\n\n```yaml\ngenerators:\n  github: your-username\n  devto: your-username\n  bluesky: handle.bsky.social\n  zodiac: aquarius\n\nplugins:\n  github:\n    enabled: true\n    username: your-username\n```\n\n```bash\n# 3. Generate! Reads sources from .mcp-me.yaml automatically\nmcp-me generate\n\n# 4. Start the MCP server\nmcp-me serve\n```\n\n> **CLI flags also work:** `mcp-me generate --github octocat --devto myuser`\n\nAll commands work with `npx` (zero install) or with `mcp-me` directly if installed globally. The `generate` command pulls your data from public APIs and auto-populates profile YAML files — no API keys needed for most sources.\n\n### Profile directory structure\n\n```\n~/.mcp-me/             → Default profile location\n  .mcp-me.yaml        → Configuration (generators + plugins)\n  identity.yaml        → Your data (name, bio, contact)\n  skills.yaml          → Your data (languages, tools)\n  projects.yaml        → Your data (portfolio)\n  career.yaml          → Your data (experience)\n  interests.yaml       → Your data (hobbies, topics)\n  personality.yaml     → Your data (traits, values)\n  goals.yaml           → Your data (short/long-term)\n  faq.yaml             → Your data (Q&A pairs)\n```\n\n## Configure Your AI Assistant\n\n### One-Click (Cursor & VS Code)\n\nUse the [one-click install badges](#one-click-install) above. After installing, run `mcp-me init` to create your profile.\n\n### Cursor Plugin (Open Plugins)\n\nmcp-me ships as a full [Open Plugins](https://open-plugins.com) plugin for Cursor. Install from [cursor.directory](https://cursor.directory) or clone the repo — the plugin auto-detects all components:\n\n| Component | Location | Purpose |\n|---|---|---|\n| MCP Server | [`mcp.json`](mcp.json) | Zero-config `npx -y mcp-me serve` |\n| Rules | [`rules/`](rules/) | Always consult profile before answering |\n| Skills | [`skills/`](skills/) | Profile usage and setup guides |\n| Agents | [`agents/`](agents/) | Profile assistant and intro writer |\n| Commands | [`commands/`](commands/) | `/ask-about-me` and `/introduce-me` |\n| Hooks | [`hooks/hooks.json`](hooks/hooks.json) | Session-start profile reminder |\n| LSP | [`.lsp.json`](.lsp.json) | YAML language server for profile files |\n\nValidate the plugin structure: `npm run validate:open-plugin`\n\n### Windsurf\n\nAdd to `~/.codeium/windsurf/mcp_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"me\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-me\", \"serve\"]\n    }\n  }\n}\n```\n\n### Cursor (manual)\n\nAdd to `.cursor/mcp.json` in your project root:\n\n```json\n{\n  \"mcpServers\": {\n    \"me\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-me\", \"serve\"]\n    }\n  }\n}\n```\n\n### VS Code (GitHub Copilot)\n\nAdd to `.vscode/mcp.json` in your project root (or in your User Settings for global access):\n\n```json\n{\n  \"servers\": {\n    \"me\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-me\", \"serve\"]\n    }\n  }\n}\n```\n\n> **Tip:** To enable it globally (all workspaces), open VS Code Settings (`Ctrl+Shift+P` → \"Preferences: Open User Settings (JSON)\") and add the `mcp` key there instead.\n\n### Claude Desktop\n\n**Option A — Desktop Extension (.mcpb, recommended):**\n\n1. Download `mcp-me.mcpb` from [GitHub Releases](https://github.com/paladini/mcp-me/releases/latest)\n2. Double-click the file, or drag it into Claude Desktop → Settings → Extensions\n3. Set your profile directory when prompted (default: `~/.mcp-me`)\n4. Run `mcp-me init` if you haven't created a profile yet\n\n**Option B — Manual config:**\n\nAdd to your Claude Desktop config:\n\n```json\n{\n  \"mcpServers\": {\n    \"me\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-me\", \"serve\"]\n    }\n  }\n}\n```\n\n## Agent Instruction Files\n\nAI agents read special Markdown files in your project to understand how they should behave. Pair them with mcp-me so that **every AI session automatically consults your profile** — no more repeating your stack, career, or preferences in every conversation.\n\n| File | Works with |\n|------|------------|\n| `AGENTS.md` (project root) | Windsurf (Cascade), OpenAI Codex, Cline, and others |\n| `.github/copilot-instructions.md` | GitHub Copilot (VS Code + GitHub.com) |\n\n**Quick setup:**\n\n```bash\n# AGENTS.md — for Windsurf, Cline, Codex, etc.\ncp \"$(npm root -g)/mcp-me/templates/AGENTS.md\" ./AGENTS.md\n\n# GitHub Copilot\nmkdir -p .github\ncp \"$(npm root -g)/mcp-me/templates/.github/copilot-instructions.md\" .github/copilot-instructions.md\n```\n\nBoth templates are included with mcp-me and tell the AI to call `ask_about_me` whenever context about you would improve the response.\n\nSee the [Agent Instructions Guide](docs/ai-instructions.md) for examples, global setup, and tips on combining with project-specific rules.\n\n## Profile Schema\n\nYour profile is a collection of YAML files:\n\n| File | Description |\n|------|-------------|\n| `identity.yaml` | Name, bio, location, languages, contact info |\n| `career.yaml` | Work experience, education, certifications |\n| `skills.yaml` | Technical and soft skills with proficiency levels |\n| `interests.yaml` | Hobbies, music, books, movies, food preferences |\n| `personality.yaml` | Values, traits, MBTI, strengths |\n| `goals.yaml` | Short, medium, and long-term goals |\n| `projects.yaml` | Personal and open-source projects |\n| `faq.yaml` | Custom Q&A pairs about yourself |\n\nSee [Schema Reference](docs/schema-reference.md) for full documentation.\n\n## MCP Interface\n\n### Resources\n\nStatic profile data exposed as MCP resources:\n\n- `me://identity` — Personal identity and contact\n- `me://career` — Professional history\n- `me://skills` — Skills and proficiencies\n- `me://interests` — Hobbies and preferences\n- `me://personality` — Personality traits and values\n- `me://goals` — Personal and professional goals\n- `me://projects` — Portfolio and projects\n- `me://faq` — Frequently asked questions\n\n### Tools\n\n- **`ask_about_me`** — Free-form question about the user\n- **`search_profile`** — Keyword search across all profile data\n\n### Prompts\n\n- **`introduce_me`** — Generate a 2-paragraph introduction\n- **`summarize_career`** — Summarize career trajectory\n- **`technical_profile`** — Describe technical skills and stack\n- **`collaboration_fit`** — Evaluate fit for a project\n\n## Generators (selected examples)\n\nGenerators run during `mcp-me generate` to auto-populate your profile from public APIs or user-provided exports. **No API keys needed** for most sources.\n\nCurrent counts:\n- **Registered generators:** 329\n- **Generator source files:** 44 single-generator files + 15 batch files (`src/generators/`)\n\n> The table below is a curated list of commonly used generators. The complete source of truth is `src/generators/index.ts`.\n\n| Category | Flag | Source | Data |\n|---|---|---|---|\n| **Code** | `--github <user>` | GitHub API | Repos, languages, stars, profile |\n| **Code** | `--gitlab <user>` | GitLab API | Projects, topics, profile |\n| **Code** | `--bitbucket <user>` | Bitbucket API | Repos, languages |\n| **Code** | `--huggingface <user>` | Hugging Face API | Models, datasets, spaces |\n| **Code** | `--kaggle <user>` | Kaggle API | Competitions, datasets, medals |\n| **Code** | `--codeberg <user>` | Gitea API | Repos, languages |\n| **Writing** | `--devto <user>` | DEV.to API | Articles, tags, reactions |\n| **Writing** | `--medium <user>` | Medium RSS | Articles, categories, article text |\n| **Writing** | `--blogger-backup <xml>` | Blogger XML export | Imported posts from a local backup, filtered by author if needed |\n| **Writing** | `--hashnode <user>` | Hashnode GraphQL | Blog posts, tags |\n| **Writing** | `--substack <user>` | Substack RSS | Newsletter posts, article text |\n| **Writing** | `--wordpress <site>` | WordPress API | Blog posts, categories, tags |\n| **Writing** | `--openlibrary <user>` | Open Library API | Books authored |\n| **Writing** | `--orcid <id>` | ORCID API | Academic publications |\n| **Writing** | `--semanticscholar <id>` | S2 API | Research papers, citations |\n| **Writing** | `--youtube <channel>` | YouTube RSS | Videos, channel info |\n| **Community** | `--stackoverflow <id>` | Stack Exchange API | Top tags, reputation, badges |\n| **Community** | `--hackernews <user>` | HN Firebase API | Karma, submissions |\n| **Community** | `--mastodon <user@host>` | Mastodon API | Posts, hashtags, bio |\n| **Community** | `--bluesky <handle>` | AT Protocol API | Posts, followers |\n| **Community** | `--reddit <user>` | Reddit JSON API | Karma, bio |\n| **Community** | `--producthunt <user>` | ProductHunt GraphQL | Launched products, upvotes |\n| **Community** | `--threads <user>` | Threads API | Bio, follower stats |\n| **Packages** | `--npm <user>` | npm Registry | Published packages |\n| **Packages** | `--pypi <pkgs>` | PyPI JSON API | Package metadata |\n| **Packages** | `--crates <user>` | Crates.io API | Rust crates |\n| **Packages** | `--dockerhub <user>` | Docker Hub API | Container images |\n| **Activity** | `--wakatime <user>` | WakaTime API | Coding time, languages, editors |\n\n### Blogger XML Backup\n\n`--blogger-backup` imports written content from a Blogger XML export file on disk. It is designed for archived or multi-author blogs where you want to recover your posts even if the site is old, partially offline, or not easily queryable through a public API.\n\nBy default it imports all post entries from the file. If the backup contains multiple authors, append `::author1,author2,...` after the file path to keep only posts whose author name or email matches one of those values.\n\nExamples:\n\n```bash\n# Import all posts from a Blogger export\nmcp-me generate --blogger-backup ~/Downloads/blog-2026-03-24.xml\n\n# Import only posts written by specific authors/emails\nmcp-me generate --blogger-backup \"~/Downloads/blog.xml::fernandopalad@gmail.com,fnpaladini@gmail.com,Fernando Paladini\"\n```\n\nHow to get the export file:\n\n1. Open Blogger and choose your blog.\n2. Go to `Settings`.\n3. In `Manage blog`, click `Back up content`.\n4. Download the XML file.\n5. Pass that file path to `--blogger-backup`.\n\nThe generator imports matching posts into `projects.yaml` with `category: article`, preserves post labels as tags, and adds summary FAQ entries about the archive.\n| **Activity** | `--letterboxd <user>` | Letterboxd RSS | Films watched, ratings |\n| **Activity** | `--goodreads <user>` | Goodreads RSS + author page | Read books, shelves, reviews, published books |\n| **Activity** | `--chess <user>` | Chess.com API | Rating, stats |\n| **Activity** | `--lichess <user>` | Lichess API | Rating, games |\n| **Activity** | `--codewars <user>` | Codewars API | Rank, honor, languages |\n| **Activity** | `--leetcode <user>` | LeetCode GraphQL | Problems solved, contests |\n| **Activity** | `--lastfm <user>` | Last.fm API | Listening history, top artists |\n| **Activity** | `--steam <id>` | Steam API | Games, playtime |\n| **Activity** | `--twitch <user>` | Twitch API | Stream info |\n| **Activity** | `--dribbble <user>` | Dribbble | Design shots, portfolio |\n| **Activity** | `--unsplash <user>` | Unsplash API | Photos, downloads, collections |\n| **Activity** | `--exercism <user>` | Exercism API | Language tracks, exercises |\n| **Activity** | `--hackerrank <user>` | HackerRank API | Badges, challenges solved |\n| **Activity** | `--anilist <user>` | AniList GraphQL | Anime/manga stats, genres |\n| **Identity** | `--gravatar <email>` | Gravatar API | Bio, linked accounts, photo |\n| **Identity** | `--keybase <user>` | Keybase API | Verified identity proofs |\n\nWant to add a new data source? See the [Generator Creation Guide](docs/creating-generators.md).\n\n## Plugins (13 live integrations)\n\nPlugins run during `mcp-me serve` and provide **real-time data** to AI assistants on every query.\n\n| Plugin | Description | Auth |\n|---|---|---|\n| **GitHub** | Live repos, activity, languages | Optional token |\n| **Spotify** | Now playing, top artists, playlists | OAuth required |\n| **LinkedIn** | Professional history from export | Local JSON file |\n| **WakaTime** | Live coding stats, languages | Optional API key |\n| **DEV.to** | Live articles, reactions | Optional API key |\n| **Bluesky** | Live posts, profile, followers | None |\n| **Hacker News** | Live stories, karma | None |\n| **Reddit** | Live karma, posts | None |\n| **GitLab** | Live projects, activity, MRs | Optional token |\n| **Mastodon** | Live toots, profile, engagement | None |\n| **YouTube** | Live videos, channel stats | Optional API key |\n| **Last.fm** | Now playing, top artists, scrobbles | Optional API key |\n| **Steam** | Currently playing, game library | Optional API key |\n\nEnable plugins in `.mcp-me.yaml`:\n\n```yaml\nplugins:\n  github:\n    enabled: true\n    username: \"your-username\"\n  spotify:\n    enabled: true\n    client_id_env: \"SPOTIFY_CLIENT_ID\"\n    client_secret_env: \"SPOTIFY_CLIENT_SECRET\"\n    refresh_token_env: \"SPOTIFY_REFRESH_TOKEN\"\n```\n\nCommunity plugins are installed from npm (`mcp-me-plugin-*`) and auto-discovered. See the [Plugin Creation Guide](docs/creating-plugins.md).\n\n## Generators vs Plugins\n\n| | Generators | Plugins |\n|---|---|---|\n| **Run when** | `mcp-me generate` (once) | `mcp-me serve` (continuously) |\n| **Output** | Static YAML files | Live MCP resources/tools |\n| **Auth** | Almost never needed | Sometimes (OAuth) |\n| **Example** | \"Repos I had in March\" | \"Repos I have right now\" |\n| **Extend** | Add `src/generators/*.ts` | Add `src/plugins/*/` |\n\n## CLI Reference\n\n```bash\n# Auto-generate profile from multiple data sources\nmcp-me generate [--directory] --github <user> [--devto <user>] [--stackoverflow <id>] ...\n\n# Initialize with blank YAML templates (defaults to ~/.mcp-me)\nmcp-me init [directory]\n\n# Validate profile YAML files\nmcp-me validate [directory]\n\n# Start the MCP server (defaults to ~/.mcp-me)\nmcp-me serve [directory]\n\n# Scaffold a new generator or plugin (for contributors)\nmcp-me create generator <name> [--category <category>]\nmcp-me create plugin <name>\n```\n\n> **Profile location:** Defaults to `~/.mcp-me`. Override with `MCP_ME_PROFILE_DIR` or pass an explicit `[directory]` argument.\n\n## Development\n\n```bash\n# Clone the repo\ngit clone https://github.com/paladini/mcp-me.git\ncd mcp-me\n\n# Install dependencies\nnpm install\n\n# Run tests\nnpm test\n\n# Build\nnpm run build\n\n# Run in dev mode\nnpm run dev\n```\n\n## FAQ\n\n**What is MCP (Model Context Protocol)?**\nMCP is an open standard by Anthropic that connects AI assistants to external data sources. mcp-me uses MCP to let AI assistants read your personal profile data.\n\n**Do I need API keys?**\nMost generators use public APIs with no auth needed. Some (Strava, Spotify) require tokens — see the `.mcp-me.yaml` comments for details.\n\n**Can I use this with Claude Desktop / VS Code / Cursor / Windsurf?**\nYes! Any MCP-compatible AI assistant works. See the [Configure Your AI Assistant](#configure-your-ai-assistant) section.\n\n**How do I make AI agents use my profile automatically?**\nDrop an `AGENTS.md` (for Windsurf, Cline, Codex) or `.github/copilot-instructions.md` (for GitHub Copilot) into your project. Templates are included — see the [Agent Instructions Guide](docs/ai-instructions.md).\n\n**How do I add a new data source?**\nRun `mcp-me create generator myservice` to scaffold a new generator, or see the [Generator Creation Guide](docs/creating-generators.md).\n\n**Is my data stored anywhere?**\nNo. All data stays local in your YAML files. The MCP server reads from disk — nothing is sent to any cloud.\n\n**How many generators are there?**\nCurrently 329 registered generators, implemented across 44 generator source files plus 15 batch files.\n\n## Contributing\n\nWe welcome contributions! Whether it's a new plugin, a bug fix, or documentation improvements — see [CONTRIBUTING.md](.github/CONTRIBUTING.md) for guidelines.\n\nMaintainers: see [Publishing Guide](docs/publishing.md) for release and distribution instructions.\n\n## License\n\n[MIT](LICENSE)\n",
  "bytes": 19749,
  "sha": "5986176e1597f6fb3f3a1c2592a8e8b48659ff37192a518663b898e15c24ea16",
  "repo_slug": "paladini/mcp-me",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_paladini_mcp_me_f1e731ac/readme"
}