diff --git a/.cursor/rules/repo-context.mdc b/.cursor/rules/repo-context.mdc new file mode 100644 index 0000000..35e640c --- /dev/null +++ b/.cursor/rules/repo-context.mdc @@ -0,0 +1,10 @@ +--- +description: Shared repo context +alwaysApply: true +--- + +Read `AGENTS.md` first. Treat it as the source of truth for this repo's +commands, invariants, public naming, release constraints, and first-user path. + +This file is a thin client adapter for Cursor. Do not add independent strategy, +roadmap, package-name, release, or baseline-scope rules here. diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..0c6e602 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,8 @@ +# Agent context + +Read `AGENTS.md` first. Treat it as the source of truth for this repo's +commands, invariants, public naming, release constraints, and first-user path. + +This file is a thin client adapter for GitHub Copilot and VS Code. Do not add +independent strategy, roadmap, package-name, release, or baseline-scope rules +here. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..3357ac5 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,89 @@ +# Python MCP Server Starter + +Python MCP server template with FastMCP, stdio transport, CI checks, and OIDC +trusted publishing to PyPI. + +## Project Structure + +``` +src/my_mcp_server/ +├── __main__.py # python -m entry point +├── server.py # FastMCP server plus inline greet tool example +├── resources/ +│ └── server_info.py # Example resource (info://server/status) +└── prompts/ + └── code_review.py # Example validated prompt +scripts/ +└── smoke_stdio.py # Stdio smoke test against the installed server +tests/ # pytest suite for tools, resources, prompts, config +pyproject.toml # Package metadata, dev deps, ruff/mypy/pytest config +``` + +## First User Path + +```bash +python3.12 -m venv .venv +source .venv/bin/activate +python -m pip install --upgrade pip +python -m pip install -e '.[dev]' +python -m pytest +python -m ruff check . +python -m ruff format --check . +python -m mypy src/ +python -m build +python scripts/smoke_stdio.py +``` + +Use Python 3.11+ if 3.12 is not available locally. CI tests 3.11, 3.12, and +3.13. + +## Adding a Tool + +For simple tools, add the decorated function in `src/my_mcp_server/server.py`: + +```python +@mcp.tool( + annotations=ToolAnnotations( + readOnlyHint=True, + destructiveHint=False, + idempotentHint=True, + openWorldHint=False, + ), +) +async def your_tool(input: str) -> str: + """Describe what the tool does.""" + return f"Processed: {input}" +``` + +For larger servers, copy the `register(mcp)` pattern from +`src/my_mcp_server/resources/server_info.py` or +`src/my_mcp_server/prompts/code_review.py`, then import and call it from +`server.py`. + +## CI/CD Pipeline + +- **ci.yml**: gitleaks, large-file check, license check, dependency audit, + ruff, pytest across supported Python versions, build, mypy, stdio smoke. +- **cd.yml**: manual PyPI publish with OIDC trusted publishing and GitHub + Release creation. +- **setup.yml**: first-push setup checklist. + +## Release Constraints + +- PyPI package names are unscoped product nouns. Do not introduce npm-style or + organization-scoped package naming. +- OIDC trusted publishing replaces long-lived `PYPI_TOKEN` secrets. +- Keep `project.urls` aligned with the final repository before publishing. +- Keep the `my-mcp-server` console script aligned with the package name or + document any intentional divergence. + +## Do Not Regress + +- Do not remove tool safety annotations. MCP clients use them to decide how to + call tools. +- Do not make tool names generic. Prefix real tools with the module or product + domain so they stay unique across connected MCP servers. +- Do not weaken ruff, mypy, pytest, license, dependency-audit, or stdio-smoke + checks without documenting the tradeoff. +- Do not add required secrets for normal CI. Publishing may require platform + setup, but CI should stay secret-free. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..5838d3c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,7 @@ +# Agent context + +Read `AGENTS.md` first. Treat it as the source of truth for this repo's +commands, invariants, public naming, release constraints, and first-user path. + +This file is a thin client adapter. Do not add independent strategy, roadmap, +package-name, release, or baseline-scope rules here. diff --git a/README.ko.md b/README.ko.md index 222096b..7234816 100644 --- a/README.ko.md +++ b/README.ko.md @@ -36,7 +36,7 @@ MCP 서버를 만들고, 원클릭 배포. 시크릿 불필요. **[create-starter](https://github.com/starter-series/create-starter) 사용** (권장): ```bash -npx @starter-series/create my-mcp-server --template mcp-server-python +gh repo create my-mcp-server --template starter-series/python-mcp-server-starter --clone cd my-mcp-server python3.12 -m venv .venv && source .venv/bin/activate python -m pip install --upgrade pip diff --git a/README.md b/README.md index fb8d580..03cdfe4 100644 --- a/README.md +++ b/README.md @@ -39,7 +39,7 @@ Build your MCP server. One-click publish. Zero secrets needed. **Via [create-starter](https://github.com/starter-series/create-starter)** (recommended): ```bash -npx @starter-series/create my-mcp-server --template mcp-server-python +gh repo create my-mcp-server --template starter-series/python-mcp-server-starter --clone cd my-mcp-server python3.12 -m venv .venv && source .venv/bin/activate python -m pip install --upgrade pip diff --git a/claude-security-guidance.md b/claude-security-guidance.md index 3a34030..f35cbda 100644 --- a/claude-security-guidance.md +++ b/claude-security-guidance.md @@ -5,7 +5,7 @@ This file is read by Anthropic's Claude Code Security Guidance Plugin It complements — does not replace — the post-PR `claude-code-security-review` GitHub Action and the repo-level `audit_security` check. -> Generated by `@starter-series/create seed-security-guidance` on 2026-06-03. +> Generated by `create-starter seed-security-guidance` on 2026-06-03. > Edit freely — the plugin re-reads this file on every session. ## Universal rules