mcp server dev
- Repo stars 0
- Author repo skills-registry
- Domain
- AI
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 88 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @tomevault-io · no license declared
- Token usage
- Lean
- Setup complexity
- Guided setup
- External API key
- Not required
- Operating systems
- macOS · Linux · Windows
- Runtime requirements
- Node.js · Python
- Detected file/system behavior
-
- Read-only
- Write / modify
- Network behavior
- Local-only
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
List every tool with its name, description, parameters, and return format. Apply the consolidation principle: prefer fewer capable tools over many narrow ones. For each tool, write the 3-4 sentence description (what, when to use, when NOT to use, behavior notes). This is the most important step — good descriptions prevent misuse.
Use the templates as starting points: Python: `templates/mcp-server-python-template/` TypeScript: `templates/mcp-server-typescript-template/` Core directory structure: Python:
Write each tool handler following the patterns in the language-specific reference: Python: `references/python-server-patterns.md` TypeScript: `references/typescript-server-patterns.md` Key principles for all tools: Validate inputs at the top of every handler
Python (uvx): Set `[project.scripts]` in `pyproject.toml`: TypeScript (npx): Set `bin` in `package.json`:
Implement graceful shutdown (SIGINT/SIGTERM handling). This is critical for clean process termination when the client disconnects.
Test at three levels: Unit: Import handler, call with dict, assert output Integration: Start server, call tools via MCP client Schema validation: Verify tool definitions match expected schemas See `references/server-testing-guide.md` for detailed patterns.
# MCP Server Creation
Create multi-tool MCP servers in Python or TypeScript that follow the Model Context Protocol specification and Anthropic's tool design best practices.
## What MCP Servers Are
An MCP server is a process that exposes one or more tools (and optionally resources and prompts) over the Model Context Protocol. Servers communicate via stdio transport — they read JSON-RPC from stdin and write responses to stdout.
MCP servers are how you package and distribute tool capabilities. An LLM client (Claude Code, Claude Desktop, etc.) starts the server process and calls its tools.
## When to Create a Server
- You have **2+ related tools** that share configuration, state, or domain
- You want to **distribute tools** for others to use (via `uvx` or `npx`)
- Tools need **shared resources** (database connections, API clients, auth tokens)
- You're building a **domain-specific toolkit** (GitHub, database, monitoring, etc.)
## When NOT to Create a Server
- Single utility tool — use a standalone tool file (see `mcp-tool-dev` skill)
- Claude Code agent, skill, or command — use their respective creation skills
- REST API — MCP is for LLM tool calling, not general HTTP services
## Python vs TypeScript
| Factor | Python (FastMCP) | TypeScript (@modelcontextprotocol/sdk) |
|--------|-------------------|----------------------------------------|
| **Distribution** | `uvx` (uv tool) | `npx` |
| **Type system** | Type hints + docstrings | Zod schemas |
| **Packaging** | `pyproject.toml` | `package.json` with bin |
| **Async** | Native `async/await` | Native `async/await` |
| **Best for** | Data science, Python tooling, API wrappers | Frontend tooling, Node.js ecosystem, npm distribution |
Choose Python when the tools interact with Python libraries or you prefer pyproject.toml packaging. Choose TypeScript when targeting the npm ecosystem or when tools interact with Node.js libraries.
## Creation Workflow
### Step 1: Design Your Tools
List every tool with its name, description, parameters, and return format. Apply the consolidation principle: prefer fewer capable tools over many narrow ones.
For each tool, write the 3-4 sentence description (what, when to use, when NOT to use, behavior notes). This is the most important step — good descriptions prevent misuse.
### Step 2: Scaffold the Project
Use the templates as starting points:
- Python: `templates/mcp-server-python-template/`
- TypeScript: `templates/mcp-server-typescript-template/`
Core directory structure:
**Python:**
```
my-server/
├── pyproject.toml # uvx entry point
├── src/my_server/
│ ├── __init__.py
│ ├── server.py # FastMCP instance + tool registration
│ └── tools/ # One file per tool or tool group
│ └── search.py
├── tests/
│ ├── conftest.py
│ └── test_tools.py
└── README.md
```
**TypeScript:**
```
my-server/
├── package.json # npx entry point with bin
├── tsconfig.json
├── src/
│ ├── index.ts # Entry: CLI args, transport, shutdown
│ ├── server.ts # Tool registration
│ └── tools/
│ └── search.ts
├── tests/
│ └── tools.test.ts
└── README.md
```
### Step 3: Implement Tools
Write each tool handler following the patterns in the language-specific reference:
- Python: `references/python-server-patterns.md`
- TypeScript: `references/typescript-server-patterns.md`
Key principles for all tools:
- Validate inputs at the top of every handler
- Return formatted text, not raw JSON dumps
- Include corrective guidance in error messages
- Keep handlers focused — one tool, one job
### Step 4: Configure Packaging
**Python (uvx):** Set `[project.scripts]` in `pyproject.toml`:
```toml
[project.scripts]
my-server = "my_server.server:main"
```
**TypeScript (npx):** Set `bin` in `package.json`:
```json
{
"bin": { "my-server": "dist/index.js" }
}
```
### Step 5: Handle Server Lifecycle
Implement graceful shutdown (SIGINT/SIGTERM handling). This is critical for clean process termination when the client disconnects.
### Step 6: Write Tests
Test at three levels:
1. **Unit**: Import handler, call with dict, assert output
2. **Integration**: Start server, call tools via MCP client
3. **Schema validation**: Verify tool definitions match expected schemas
See `references/server-testing-guide.md` for detailed patterns.
## Tool Description Best Practices
- Write 3-4 sentences: what, when to use, when not to use, behavior notes
- Include parameter semantics in descriptions (regex vs full-text, format expectations)
- For 10+ tools, use discovery-first architecture: provide a `list_capabilities` tool
## Common Mistakes
1. **No graceful shutdown** — server hangs when client disconnects; always handle SIGINT/SIGTERM
2. **Stdout pollution** — logging or print() to stdout corrupts JSON-RPC; use stderr for logging
3. **Missing tool descriptions** — tools without descriptions are invisible to the LLM
4. **Monolithic handlers** — 200-line tool handlers; split logic into helper functions
5. **No packaging config** — forgetting `[project.scripts]` or `bin` entry; server can't be installed
6. **Ignoring transport** — MCP uses stdio, not HTTP; don't create an HTTP server
For detailed patterns per language, see the `references/` directory.
---
> Source: [andisab/swe-marketplace](https://github.com/andisab/swe-marketplace) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-23 -->
Listed in source order.
sections -> What MCP Servers Are → When to Create a Server → When NOT to Create a Server → Python vs TypeScript → Creation Workflow → Step 1: Design Your Tools
terms -> 2+ related tools · distribute tools · shared resources · domain-specific toolkit · Distribution · Type system · Packaging · Async
files/cmd -> uvx · npx · mcp-tool-dev · pyproject.toml · package.json · async/await · templates/mcp-server-python-template/ · templates/mcp-server-typescript-template/
body sha256 -> ae61c2a685f3
What MCP Servers Are
An MCP server is a process that exposes one or more tools (and optionally resources and prompts) over the Model Context Protocol. Servers communicate via stdio transport — they read JSON-RPC from stdin and write responses to stdout. MCP servers are how you package and distribute tool capabilities. An LLM client (Claude Code, Claude Desktop, etc.) starts the server process and calls its tools.
When to Create a Server
You have 2+ related tools that share configuration, state, or domain You want to distribute tools for others to use (via
uvxornpx) Tools need shared resources (database connections, API clients, auth tokens) You're building a domain-specific toolkit (GitHub, database, monitoring, etc.)When NOT to Create a Server
Single utility tool — use a standalone tool file (see
mcp-tool-devskill) Claude Code agent, skill, or command — use their respective creation skills REST API — MCP is for LLM tool calling, not general HTTP servicesPython vs TypeScript
Factor · Python (FastMCP) · TypeScript (@modelcontextprotocol/sdk) Distribution ·
uvx(uv tool) ·npxType system · Type hints + docstrings · Zod schemas Packaging ·pyproject.toml·package.jsonwith bin Async · Nativeasync/await· Nativeasync/awaitStep 1: Design Your Tools
List every tool with its name, description, parameters, and return format. Apply the consolidation principle: prefer fewer capable tools over many narrow ones. For each tool, write the 3-4 sentence description (what, when to use, when NOT to use, behavior notes). This is the most important step — good descriptions prevent misuse.