{"id":51194643,"url":"https://github.com/ejoliet/mcp-starter","last_synced_at":"2026-06-27T19:01:44.894Z","repository":{"id":357730605,"uuid":"1238290210","full_name":"ejoliet/mcp-starter","owner":"ejoliet","description":"MCP starter or how to learn devlopping a mcp server","archived":false,"fork":false,"pushed_at":"2026-05-14T02:07:43.000Z","size":39,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-14T04:16:31.177Z","etag":null,"topics":["claude-code","learning-by-doing","mcp-server","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ejoliet.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-14T01:50:57.000Z","updated_at":"2026-05-14T02:10:33.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ejoliet/mcp-starter","commit_stats":null,"previous_names":["ejoliet/mcp-starter"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/ejoliet/mcp-starter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ejoliet%2Fmcp-starter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ejoliet%2Fmcp-starter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ejoliet%2Fmcp-starter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ejoliet%2Fmcp-starter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ejoliet","download_url":"https://codeload.github.com/ejoliet/mcp-starter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ejoliet%2Fmcp-starter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34864431,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-27T02:00:06.362Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-code","learning-by-doing","mcp-server","python"],"created_at":"2026-06-27T19:01:44.128Z","updated_at":"2026-06-27T19:01:44.882Z","avatar_url":"https://github.com/ejoliet.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mcp-starter\n\nA minimal MCP (Model Context Protocol) server that demonstrates the three core capability types — **Tools**, **Resources**, and **Prompts** — through a simple notes app.\n\nUse this as a learning template or starting point for building your own MCP server.\n\n## What's inside\n\n| Capability | Name | What it does |\n|---|---|---|\n| Tool | `add_note` | Save a note with a title and body |\n| Tool | `list_notes` | List all note IDs and titles |\n| Tool | `delete_note` | Delete a note by ID |\n| Resource | `notes://all` | Read full content of all notes as JSON |\n| Prompt | `summarize_notes` | Ask Claude to summarize all notes as bullet points |\n\nNotes are persisted to `notes.json` alongside `server.py`.\n\n## Install\n\n### One-liner (bash)\n\nRequires [uv](https://docs.astral.sh/uv/) and [Claude Code](https://claude.ai/code).\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/ejoliet/mcp-starter/main/install.sh | bash\n```\n\nThis clones the repo to `~/mcp-starter`, installs dependencies, and registers the server with Claude Code automatically. Start a new Claude Code session and it's ready.\n\nTo install to a custom path:\n\n```bash\nMCP_STARTER_DIR=~/dev/mcp-starter curl -fsSL https://raw.githubusercontent.com/ejoliet/mcp-starter/main/install.sh | bash\n```\n\n### Docker\n\nRequires [Docker](https://docs.docker.com/get-docker/).\n\n```bash\ngit clone https://github.com/ejoliet/mcp-starter.git\ncd mcp-starter\ndocker compose up --build\n```\n\nNotes are persisted in a named Docker volume (`notes-data`). Register the containerized server with Claude Code:\n\n```bash\nclaude mcp add mcp-starter -- docker compose -f ~/mcp-starter/docker-compose.yml run --rm mcp-starter\n```\n\n### Manual setup\n\nRequirements: Python 3.12+, [uv](https://docs.astral.sh/uv/), Claude Code.\n\n```bash\ngit clone https://github.com/ejoliet/mcp-starter.git ~/mcp-starter\ncd ~/mcp-starter\nuv sync\nclaude mcp add mcp-starter -- uv --directory ~/mcp-starter run server.py\n```\n\nThen start a new Claude Code session — the server will be available automatically.\n\n## Usage in Claude\n\nOnce registered, Claude can call tools directly:\n\n\u003e \"Add a note titled 'standup' with body 'review PR #42'\"  \n\u003e \"List my notes\"  \n\u003e \"Delete note #1\"\n\nOr read the resource and prompt via the MCP panel (`/mcp`).\n\n## CLI development \u0026 testing\n\nSee [DEV_GUIDE.md](DEV_GUIDE.md) for how to iterate on the server from the terminal without relying on Claude Code.\n\nQuick test:\n\n```bash\nuv run python test_resource.py\n```\n\n## Project structure\n\n```\nmcp-starter/\n├── server.py          # MCP server implementation\n├── test_resource.py   # CLI test harness\n├── install.sh         # Bash one-liner installer\n├── Dockerfile         # Container image\n├── docker-compose.yml # Compose config\n├── pyproject.toml     # Dependencies\n└── DEV_GUIDE.md       # Developer iteration guide\n```\n\n## Extending\n\nAdd a new tool in `server.py`:\n1. Append a `types.Tool(...)` entry in `list_tools()`\n2. Handle `name == \"your_tool\"` in `call_tool()`\n3. Test with `test_resource.py` before restarting Claude Code\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fejoliet%2Fmcp-starter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fejoliet%2Fmcp-starter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fejoliet%2Fmcp-starter/lists"}