Portfolio MCP Server
Portfolio MCP Server
一个 MCP 服务器,将我的 AI 项目作品集变成你可以查询的东西,而不仅仅是阅读。
将任何 MCP 客户端(Claude Desktop、Cursor、自定义代理)指向它,然后问 "Ayush 用 LangGraph 构建了什么?" 或 "他的旗舰项目是什么?" — 它会从实时结构化数据中回答,而不是静态 PDF。
TL;DR
📦 已发布,而不仅仅是构建完成 — 已上线 PyPI 和官方 MCP 注册表;
pip install portfolio-mcp-server可让它在不到一分钟内运行在任何 MCP 客户端中,无需克隆仓库。🔧 5 个真实工具 — 列表、详情查询、技术栈搜索、旗舰项目挑选和简历摘要,全部由结构化数据支撑,而不是滚动浏览静态 README。
✅ 每次推送都经过 CI 测试 — 代码检查、类型检查,以及一个真实的 stdio 冒烟测试,调用全部 5 个工具并验证每个响应的 JSON schema。
目录
Related MCP server: toad-mcp-server
为什么存在
大多数 AI 开发者作品集只是一堆链接。这是一个可运行的 MCP 服务器 — 代理型产品用来连接工具所用的同一协议 — 围绕我自己的作品集构建。 它既是对规范的真实实现,也是对 "证明你真的用 MCP 构建过东西" 的回应, 而不仅仅是纸上谈兵。
演示
MCP Inspector — 工具发现 | 实时聊天演示 |
|
|
https://github.com/user-attachments/assets/4c1b844a-087f-48a6-b156-bdef27282acc
设置 → 工具调用 → 实时回答,端到端。
暴露的工具
工具 | 描述 |
| 全部 9 个项目的简短摘要 |
| 单个项目的完整详情 |
| 查找使用指定技术的项目 |
| 最值得优先查看的一个项目 |
| 背景、目标职位和核心技术栈 |
快速开始
选项 A — 从 PyPI 安装(最快):
pip install portfolio-mcp-server选项 B — 克隆并从源码运行(用于本地修改/测试):
git clone https://github.com/ayush-s-tomar/portfolio-mcp-server.git
cd portfolio-mcp-server
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -r requirements.txt在接入客户端之前,先用 MCP Inspector 交互式测试:
mcp dev server.py这会打开一个浏览器界面,你可以手动调用每个工具并检查原始的请求/响应负载。
连接 Claude Desktop
打开你的 Claude Desktop 配置文件:
OS | 路径 |
macOS |
|
Windows |
|
如果文件中已有包含其他服务器的 mcpServers 键,请在现有对象内添加
"portfolio" 条目,而不是覆盖整个文件。
如果你通过 PyPI 安装(上面的选项 A):
{
"mcpServers": {
"portfolio": {
"command": "portfolio-mcp-server"
}
}
}如果你是从克隆的源码运行(上面的选项 B): 请使用你机器上 server.py 的绝对路径:
{
"mcpServers": {
"portfolio": {
"command": "python",
"args": ["/absolute/path/to/portfolio-mcp-server/server.py"]
}
}
}重启 Claude Desktop,然后问它类似这样的问题:
"Ayush 用 FastAPI 构建了哪些项目?"
Claude 会调用 search_projects_by_stack 并从实时数据中回答。
技术栈
Python 3.10+
MCP Python SDK(
FastMCP)stdio 传输
打包发布到 PyPI,并注册到官方 MCP 服务器注册表(
io.github.ayush-s-tomar/portfolio-mcp-server)
测试与 CI
每次推送和拉取请求都会经过 GitHub Actions 运行:
代码检查 —
ruff check .类型检查 —
mypy server.py冒烟测试 — 启动服务器并通过 stdio 调用全部 5 个工具,确认它们返回有效且符合 schema 的 JSON
参见 .github/workflows/ci.yml。在提交 PR 之前,请在本地运行相同的检查:
pip install -r requirements-dev.txt
ruff check .
mypy server.py
pytest项目结构
portfolio-mcp-server/ ├── server.py # FastMCP 服务器 + 工具定义 ├── data/ │ └── projects.json # 工具读取的项目数据 ├── tests/ │ └── test_tools.py # 每个工具的冒烟测试 ├── requirements.txt ├── requirements-dev.txt ├── pyproject.toml # PyPI 打包配置 ├── server.json # MCP 注册表清单 └── .github/workflows/ci.yml
路线图
作为可安装包发布到 PyPI
发布到官方 MCP 服务器注册表
search_projects_by_stack— 支持同时匹配多种技术在 stdio 之外增加 HTTP/SSE 传输选项,以支持远程客户端
使用轻量级刷新端点缓存简历/项目数据,而不是静态 JSON
许可证
基于 MIT 许可证 发布。
作者
Ayush Tomar — GitHub
如果这个项目对构建你自己的 MCP 服务器有参考价值,欢迎在仓库上点一个 ⭐。
mcp-name: io.github.ayush-s-tomar/portfolio-mcp-server
Available Tools
7 toolsget_data_infoARead-onlyIdempotent
Say how current the portfolio data is: its date, whether it came from the live repository or the copy bundled with the installed package, how many projects it holds, and the package version.
Inputs: no named parameters. Returns: object
get_flagship_projectARead-onlyIdempotent
Get Ayush's flagship project, the one to look at first for a quick sense of his skill level.
Inputs: no named parameters. Returns: object
get_project_detailsARead-onlyIdempotent
Get full details for one project by name.
Matching is case-insensitive: an exact name wins, then a name prefix, then any part of a name ('sales' finds SalesAgent), then the words in a description ('RAG chatbot' finds AskMyDocs). If several projects match, the best one is returned and the others are listed under 'also_matches'.
Returns description, full stack, GitHub repo, live demo link, and writeup link if one exists.
Inputs: project_name (required). Returns: object
get_resume_summaryARead-onlyIdempotent
Get a summary of Ayush's background: education, target role, core tech stack, and career highlights.
Inputs: no named parameters. Returns: object
list_projectsARead-onlyIdempotent
List all projects in Ayush's portfolio with a short summary of each.
Returns a compact list (name, short description, stack). Use get_project_details for the full description, GitHub link, and demo URL.
Inputs: no named parameters. Returns: result
match_job_descriptionARead-onlyIdempotent
Rank Ayush's projects against a pasted job description.
Finds the technologies and topics in the text (LangGraph, FastAPI, RAG, agents, ...) and scores each project by how many it covers. This is a keyword overlap, a quick way to see which projects to open first. It is not an assessment of fit.
Inputs: job_description (required), top_n. Returns: object
search_projects_by_stackARead-onlyIdempotent
Find projects that use one or more technologies or topics.
Case-insensitive, partial names match ('lang' finds LangGraph). Separate several with commas, '+', '&' or 'and' to require all of them, e.g. 'LangGraph and FastAPI'. Common topics are understood too: 'RAG', 'agents', 'voice', 'fine-tuning', 'frontend', 'backend'.
Useful for answering "does Ayush have experience with X?"
Inputs: technology (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool targets a distinct need: listing, single-project detail, stack filtering, JD matching, flagship shortcut, resume summary, and data provenance. Descriptions explicitly cross-reference each other (list_projects points to get_project_details) and clarify boundaries. get_flagship_project slightly overlaps with get_project_details but has a clearly different presentation purpose.
All names are snake_case with a verb-first pattern (list_, get_, search_, match_) followed by a clear resource or concept. The two non-'get' verbs (search_projects_by_stack, match_job_description) still follow verb_object convention and read predictably.
Seven tools is well-scoped for a personal portfolio server — every tool maps to a real question a recruiter or agent would ask. Nothing feels redundant or padded.
The read-only surface covers browsing, detail, tech search, JD matching, resume, and data freshness with no dead ends. Minor gaps: no way to retrieve contact/social links or enumerate all technologies directly, though get_resume_summary and search partially cover this.
Maintenance
Related MCP Connectors
MCP server for generating rough-draft project plans from natural-language prompts.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
One MCP server for the services your AI needs: memory, files, Microsoft 365, kanban and more.
Related MCP Servers
- AlicenseAqualityDmaintenanceAn MCP server that lets recruiters and AI assistants explore your profile, skills, and projects through natural language.6MIT
- AlicenseAqualityDmaintenanceMCP server exposing portfolio AI tools including semantic search, evaluation framework, and prompt management, enabling natural language interaction with these services via Claude Desktop.5ISC
- FlicenseNot gradedqualityDmaintenanceAn MCP server for controlling the TimeLiner project management system, enabling AI clients to manage projects, tasks, members, and more via natural language.-
- FlicenseNot gradedqualityCmaintenanceAn MCP server that enables AI assistants to interact with OpenProject, listing projects and work packages and managing resources through natural language.-

