building-mcp-servers

Name: building-mcp-servers
Author: mjunaidca

21installs11forks

How to install building-mcp-servers?

mjunaidca/mjs-agent-skills/building-mcp-servers

$npx -y skills add mjunaidca/mjs-agent-skills --skill building-mcp-servers

Installs into the current project.

Summary

Guides creation of high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). Co

Files · 1

View on GitHub

SKILL.md

1	# MCP Server Development Guide
2
3	## Overview
4
5	Create MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. The quality of an MCP server is measured by how well it enables LLMs to accomplish real-world tasks.
6
7	---
8
9	## High-Level Workflow
10
11	Creating a high-quality MCP server involves four main phases:
12
13	### Phase 1: Deep Research and Planning
14
15	#### 1.1 Understand Modern MCP Design
16
17	API Coverage vs. Workflow Tools:
18	Balance comprehensive API endpoint coverage with specialized workflow tools. When uncertain, prioritize comprehensive API coverage.
19
20	Tool Naming and Discoverability:
21	Use consistent prefixes (e.g., `github_create_issue`, `github_list_repos`) and action-oriented naming.
22
23	Context Management:
24	Design tools that return focused, relevant data. Support filtering/pagination.
25
26	Actionable Error Messages:
27	Error messages should guide agents toward solutions with specific suggestions.
28
29	#### 1.2 Study MCP Protocol Documentation
30
31	Start with the sitemap: `https://modelcontextprotocol.io/sitemap.xml`
32
33	Fetch pages with `.md` suffix (e.g., `https://modelcontextprotocol.io/specification/draft.md`).
34
35	Key pages: Specification overview, transport mechanisms, tool/resource/prompt definitions.
36
37	#### 1.3 Study Framework Documentation
38
39	Recommended stack:
40	- Language: TypeScript (high-quality SDK, good AI code generation)
41	- Transport: Streamable HTTP for remote servers, stdio for local servers
42
43	Load framework documentation:
44	- [MCP Best Practices](references/mcp_best_practices.md) - Core guidelines
45	- [TypeScript Guide](references/node_mcp_server.md) - TypeScript patterns
46	- [Python Guide](references/python_mcp_server.md) - Python/FastMCP patterns
47
48	SDK Documentation:
49	- TypeScript: `https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md`
50	- Python: `https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md`
51
52	#### 1.4 Plan Your Implementation
53
54	Review the service's API documentation. List endpoints to implement, starting with most common operations.
55
56	---
57
58	### Phase 2: Implementation
59
60	#### 2.1 Set Up Project Structure
61
62	See language-specific guides:
63	- [TypeScript Guide](references/node_mcp_server.md) - Project structure, package.json, tsconfig.json
64	- [Python Guide](references/python_mcp_server.md) - Module organization, dependencies
65
66	#### 2.2 Implement Core Infrastructure
67
68	Create shared utilities:
69	- API client with authentication
70	- Error handling helpers
71	- Response formatting (JSON/Markdown)
72	- Pagination support
73
74	#### 2.3 Implement Tools
75
76	For each tool:
77
78	Input Schema:
79	- Use Zod (TypeScript) or Pydantic (Python)
80	- Include constraints and clear descriptions
81
82	Output Schema:
83	- Define `outputSchema` where possible
84	- Use `structuredContent` in responses
85
86	Tool Description:
87	- Concise summary, parameter descriptions, return type
88
89	Annotations:
90	- `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`
91
92	---
93
94	### Phase 3: Review and Test
95
96	#### 3.1 Code Quality
97
98	Review for: DRY principle, consistent error handling, full type coverage, clear descriptions.
99
100	#### 3.2 Build and Test
101
102	TypeScript:
103	```bash
104	npm run build
105	npx @modelcontextprotocol/inspector
106	```
107
108	Python:
109	```bash
110	python -m py_compile your_server.py
111	# Test with MCP Inspector
112	```
113
114	---
115
116	### Phase 4: Create Evaluations
117
118	Create 10 evaluation questions to test LLM effectiveness with your server.
119
120	Requirements for each question:
121	- Independent, read-only, complex, realistic, verifiable, stable
122
123	Output Format:
124	```xml
125	<evaluation>
126	<qa_pair>
127	<question>Your question here</question>
128	<answer>Expected answer</answer>
129	</qa_pair>
130	</evaluation>
131	```
132
133	See [Evaluation Guide](references/evaluation.md) for complete guidelines.
134
135	---
136
137	## Docker/Containerization
138
139	### Transport Security (allowed_hosts)
140
141	FastMCP validates Host headers. For Docker, configure:
142
143	```python
144	from mcp.server.fastmcp import FastMCP
145	from mcp.server.transport_security import TransportSecuritySettings
146
147	transport_security = TransportSecuritySettings(
148	allowed_hosts=[
149	"127.0.0.1:", "localhost:", "[::1]:*",
150	"mcp-server:*", # Docker container name
151	"0.0.0.0:*",
152	],
153	)
154	mcp = FastMCP("my_server", transport_security=transport_security)
155	```
156
157	### Health Check Endpoint
158
159	Add `/health` endpoint via middleware (see references for full example).
160
161	---
162
163	## Verification
164
165	Run: `python3 scripts/verify.py`
166
167	Expected: `✓ building-mcp-servers skill ready`
168
169	## If

People who liked this also viewed

6 picks

Type

building-mcp-servers

21installs11forks

View on GitHub

How to install building-mcp-servers?

mjunaidca/mjs-agent-skills/building-mcp-servers

$npx -y skills add mjunaidca/mjs-agent-skills --skill building-mcp-servers

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# MCP Server Development Guide
2
3	## Overview
4
5	Create MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. The quality of an MCP server is measured by how well it enables LLMs to accomplish real-world tasks.
6
7	---
8
9	## High-Level Workflow
10
11	Creating a high-quality MCP server involves four main phases:
12
13	### Phase 1: Deep Research and Planning
14
15	#### 1.1 Understand Modern MCP Design
16
17	API Coverage vs. Workflow Tools:
18	Balance comprehensive API endpoint coverage with specialized workflow tools. When uncertain, prioritize comprehensive API coverage.
19
20	Tool Naming and Discoverability:
21	Use consistent prefixes (e.g., `github_create_issue`, `github_list_repos`) and action-oriented naming.
22
23	Context Management:
24	Design tools that return focused, relevant data. Support filtering/pagination.
25
26	Actionable Error Messages:
27	Error messages should guide agents toward solutions with specific suggestions.
28
29	#### 1.2 Study MCP Protocol Documentation
30
31	Start with the sitemap: `https://modelcontextprotocol.io/sitemap.xml`
32
33	Fetch pages with `.md` suffix (e.g., `https://modelcontextprotocol.io/specification/draft.md`).
34
35	Key pages: Specification overview, transport mechanisms, tool/resource/prompt definitions.
36
37	#### 1.3 Study Framework Documentation
38
39	Recommended stack:
40	- Language: TypeScript (high-quality SDK, good AI code generation)
41	- Transport: Streamable HTTP for remote servers, stdio for local servers
42
43	Load framework documentation:
44	- [MCP Best Practices](references/mcp_best_practices.md) - Core guidelines
45	- [TypeScript Guide](references/node_mcp_server.md) - TypeScript patterns
46	- [Python Guide](references/python_mcp_server.md) - Python/FastMCP patterns
47
48	SDK Documentation:
49	- TypeScript: `https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md`
50	- Python: `https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md`
51
52	#### 1.4 Plan Your Implementation
53
54	Review the service's API documentation. List endpoints to implement, starting with most common operations.
55
56	---
57
58	### Phase 2: Implementation
59
60	#### 2.1 Set Up Project Structure
61
62	See language-specific guides:
63	- [TypeScript Guide](references/node_mcp_server.md) - Project structure, package.json, tsconfig.json
64	- [Python Guide](references/python_mcp_server.md) - Module organization, dependencies
65
66	#### 2.2 Implement Core Infrastructure
67
68	Create shared utilities:
69	- API client with authentication
70	- Error handling helpers
71	- Response formatting (JSON/Markdown)
72	- Pagination support
73
74	#### 2.3 Implement Tools
75
76	For each tool:
77
78	Input Schema:
79	- Use Zod (TypeScript) or Pydantic (Python)
80	- Include constraints and clear descriptions
81
82	Output Schema:
83	- Define `outputSchema` where possible
84	- Use `structuredContent` in responses
85
86	Tool Description:
87	- Concise summary, parameter descriptions, return type
88
89	Annotations:
90	- `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`
91
92	---
93
94	### Phase 3: Review and Test
95
96	#### 3.1 Code Quality
97
98	Review for: DRY principle, consistent error handling, full type coverage, clear descriptions.
99
100	#### 3.2 Build and Test
101
102	TypeScript:
103	```bash
104	npm run build
105	npx @modelcontextprotocol/inspector
106	```
107
108	Python:
109	```bash
110	python -m py_compile your_server.py
111	# Test with MCP Inspector
112	```
113
114	---
115
116	### Phase 4: Create Evaluations
117
118	Create 10 evaluation questions to test LLM effectiveness with your server.
119
120	Requirements for each question:
121	- Independent, read-only, complex, realistic, verifiable, stable
122
123	Output Format:
124	```xml
125	<evaluation>
126	<qa_pair>
127	<question>Your question here</question>
128	<answer>Expected answer</answer>
129	</qa_pair>
130	</evaluation>
131	```
132
133	See [Evaluation Guide](references/evaluation.md) for complete guidelines.
134
135	---
136
137	## Docker/Containerization
138
139	### Transport Security (allowed_hosts)
140
141	FastMCP validates Host headers. For Docker, configure:
142
143	```python
144	from mcp.server.fastmcp import FastMCP
145	from mcp.server.transport_security import TransportSecuritySettings
146
147	transport_security = TransportSecuritySettings(
148	allowed_hosts=[
149	"127.0.0.1:", "localhost:", "[::1]:*",
150	"mcp-server:*", # Docker container name
151	"0.0.0.0:*",
152	],
153	)
154	mcp = FastMCP("my_server", transport_security=transport_security)
155	```
156
157	### Health Check Endpoint
158
159	Add `/health` endpoint via middleware (see references for full example).
160
161	---
162
163	## Verification
164
165	Run: `python3 scripts/verify.py`
166
167	Expected: `✓ building-mcp-servers skill ready`
168
169	## If

People who liked this also viewed

6 picks

Type