<div align="center">

# mcp-server-template

**开箱即用的 TypeScript MCP server 模板：股票 / 天气 / RSS / 文件示例，免 API key**

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
[![Node.js ≥ 18](https://img.shields.io/badge/node-%E2%89%A5%2018-brightgreen)](https://nodejs.org)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue)](https://www.typescriptlang.org)
[![MCP](https://img.shields.io/badge/MCP-stdio-blueviolet)](https://modelcontextprotocol.io)

</div>

![mcp-server-template connects MCP clients like Claude Desktop and Cursor to three stock markets, weather, RSS and local files through one stdio server — no API keys required](./assets/hero.jpg)

> A batteries-included **TypeScript template for building MCP servers** — clone it, add one file, and your tool is live in Claude Desktop, Cursor, or Kimi Code.

**mcp-server-template** is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server scaffold built on the official [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk). It ships with **6 working examples** covering the three MCP primitives (tools, resources, prompts) and the patterns you'll actually need: JSON APIs, non-JSON text APIs, XML feeds, and local file access. All data sources are **free and key-less**, so every example runs the moment you clone.

> "The Model Context Protocol is an open standard that enables developers to build secure, two-way connections between their data sources and AI-powered tools." — [Anthropic, introducing MCP](https://www.anthropic.com/news/model-context-protocol)

[English](#why-this-template) · [中文说明](#中文说明)

**Contents**: [Why this template](#why-this-template) · [Included examples](#included-examples) · [Quick start](#quick-start) · [Architecture](#architecture) · [Add your own tool](#add-your-own-tool) · [Project structure](#project-structure) · [FAQ](#faq) · [局限与已知问题](#局限与已知问题limitations)

## Why this template

- **One file = one tool group**: drop a file into `src/tools/`, register it in one line, done
- **Real examples, not stubs**: stock quotes (A-share/HK/US), weather, RSS reader, file word count — each demonstrating a different integration pattern
- **Beyond tools**: working Resource and Prompt examples most templates skip
- **Testable by design**: business logic lives in `src/lib/`, decoupled from the MCP protocol
- **Grows with you**: start as one server; the docs show how to split into multiple servers or a monorepo when you outgrow it

## Included examples

| Tool / Capability | What it does | Pattern it teaches |
| --- | --- | --- |
| `get_stock_quote` | Realtime quotes for A-share, HK, US stocks | Text-based API, GBK decoding, batch input, graceful errors |
| `search_stock` | Search stocks by name / pinyin / code | Query normalization, unicode escaping |
| `get_current_weather` | Current weather for any city | Chained JSON API calls (geocode → forecast) |
| `read_rss_feed` | Latest entries from any RSS/Atom feed | XML fetching & parsing |
| `count_file_words` | Line/word/char count of a local file | Filesystem access & safety limits |
| Resource `info://server` | Server metadata as JSON | Exposing read-only data |
| Prompt `stock_briefing` | One-click stock comparison report | Prompt templates that orchestrate tools |

Data sources: [Tencent quote API](https://qt.gtimg.cn) (stocks) and [Open-Meteo](https://open-meteo.com) (weather) — both free, no API key.

## Quick start

Requires Node.js ≥ 18.

```bash
# Click "Use this template" on GitHub, or clone directly:
git clone https://github.com/JingHao-Leon/mcp-server-template.git
cd mcp-server-template
npm install
npm run build
```

### Connect your MCP client

**Claude Desktop / Cursor** — add to your `mcpServers` config:

```json
{
  "mcpServers": {
    "my-tools": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-template/dist/index.js"]
    }
  }
}
```

**Kimi Code**:

```bash
kimi mcp add my-tools -- node /absolute/path/to/mcp-server-template/dist/index.js
```

Then try: *"查一下茅台和苹果的实时行情"* or *"Read https://hnrss.org/frontpage and summarize the top stories"*.

## Add your own tool

Three steps, ~5 minutes — full walkthrough in [CONTRIBUTING.md](./CONTRIBUTING.md):

```ts
// src/tools/my-tool.ts
import { z } from "zod";
import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

export function registerMyTools(server: McpServer): void {
  server.registerTool(
    "my_tool",
    {
      description: "What it does and when to use it",
      inputSchema: { input: z.string().describe("...") },
    },
    async ({ input }) => ({
      content: [{ type: "text" as const, text: `result: ${input}` }],
    }),
  );
}
```

```ts
// src/tools/index.ts — one line:
registerMyTools(server);
```

`npm run build`, restart your client, and the AI can call it.

## Architecture

Clients talk to the server over stdio (JSON-RPC); the server fans out to free data sources. Each box in `src/tools/`, `src/resources/`, and `src/prompts/` is one file — copy it to add your own capability.

![Architecture: MCP clients (Claude Desktop, Cursor, Kimi Code) call 5 tools, 1 resource and 1 prompt in the server over stdio; the server fetches from Tencent quote API, Open-Meteo, RSS feeds and the local filesystem — all without API keys](./assets/architecture.svg)

## Project structure

```
src/
├── index.ts        # entry: creates the server, registers everything
├── tools/          # one file = one tool group (the pattern to copy)
├── lib/            # business logic, decoupled from MCP — unit-test it directly
├── resources/      # Resource example
└── prompts/        # Prompt example
docs/
└── multi-server.md # when & how to split into multiple servers / a monorepo
CONTRIBUTING.md     # the 5-minute "add a tool" guide
```

## FAQ

**Do the examples need any API key?**
No. Stocks come from Tencent's public endpoints, weather from Open-Meteo. Everything runs immediately after `npm install && npm run build`.

**Which MCP clients work with this?**
Any client supporting stdio MCP servers: Claude Desktop, Cursor, Kimi Code, and others.

**How do I test my tool without a client?**
Call the `lib/` functions directly with `node --input-type=module -e`, or run the JSON-RPC smoke test in [CONTRIBUTING.md](./CONTRIBUTING.md).

**When should I split my server into multiple servers?**
When you exceed ~20 tools, have different trust boundaries, or need remote deployment. See [docs/multi-server.md](./docs/multi-server.md).

**Can I use this commercially?**
Yes, MIT licensed. Note the bundled stock data source is unofficial and has no SLA — swap in a licensed feed (iFinD, Polygon, Finnhub) for production.

---

*Last updated: 2026-09-21. This repo ships an [llms.txt](./llms.txt) so AI agents can consume the project structure directly.*

## 局限与已知问题（Limitations）

以下局限均由当前代码推导，使用前请知悉：

- **仅支持 stdio 传输，无鉴权**：`src/index.ts` 只注册了 `StdioServerTransport`，未内置 SSE / Streamable HTTP，也没有任何身份验证机制，适合在本地受信任环境配合 Claude Desktop / Cursor 等客户端使用；远程部署需自行改造（拆分思路见 [docs/multi-server.md](./docs/multi-server.md)）。
- **文件工具无目录白名单**：`count_file_words` 可读取 Node 进程权限内任意路径的文本文件，仅有 5MB 大小上限（`MAX_FILE_BYTES`），没有目录白名单——与代码注释一致，只应在受信任的本地环境启用，生产环境需自行加目录限制。
- **股票数据源是非官方公开接口**：行情与搜索依赖 `qt.gtimg.cn` / `smartbox.gtimg.cn`，按 `~` 分隔的位置约定解析字段（`src/lib/tencent.ts`），接口布局变更即失效，且无 SLA；行情为实时快照，不含历史 K 线，PB 仅 A 股返回、美股无总市值。
- **天气工具只覆盖"当前时刻"**：`get_current_weather` 仅返回当前天气（请求参数只有 `current=`），不含预报；地理编码只取第一个匹配城市（`count=1`）；WMO 天气码只翻译了常见子集，未覆盖的码显示"未知（code X）"。
- **RSS 解析是零依赖的正则提取**：`src/tools/rss.ts` 用正则处理标准 RSS 2.0 / Atom 源，对 CDATA 嵌套、命名空间等非常规结构可能解析失败或漏条目；生产环境建议按代码注释提示换成 fast-xml-parser 等正规解析器。
- **未附带自动化测试与 CI**：`package.json` 只有 `build` / `start` 两个脚本，仓库无测试框架配置；`src/lib/` 与协议解耦的架构只是让测试变容易，测试本身需自行补充。

## License

[MIT](./LICENSE)

---

## 中文说明

一个**开箱即用的 TypeScript MCP server 模板**：clone 下来、加一个文件，你的工具就能在 Claude Desktop / Cursor / Kimi Code 里被 AI 直接调用。

### 模板里有什么

- **6 个可直接运行的示例**：股票行情（A股/港股/美股）、股票搜索、天气、RSS 阅读、文件统计，外加 Resource 和 Prompt 示例
- **每个示例教一种模式**：标准 JSON API、非 JSON 文本接口（GBK 解码）、XML 抓取、本地文件访问
- **数据源全部免费免 key**：腾讯行情 + Open-Meteo，clone 即可跑
- **可测试的架构**：业务逻辑在 `src/lib/`，不依赖 MCP 协议，可单独测试
- **扩展路径清晰**：单服务起步，需要时按 `docs/multi-server.md` 拆成多服务或 monorepo

### 快速开始

```bash
git clone https://github.com/JingHao-Leon/mcp-server-template.git
cd mcp-server-template && npm install && npm run build
```

在 MCP 客户端的 `mcpServers` 配置中加入：

```json
{
  "mcpServers": {
    "my-tools": {
      "command": "node",
      "args": ["/绝对路径/mcp-server-template/dist/index.js"]
    }
  }
}
```

### 添加自己的工具

1. 在 `src/tools/` 新建文件，仿照示例写一个 `registerXxxTools(server)` 函数
2. 在 `src/tools/index.ts` 里 import 并调用一行
3. `npm run build`，重启客户端

详细指南见 [CONTRIBUTING.md](./CONTRIBUTING.md)。

### 数据源说明

股票行情来自腾讯公开接口（`qt.gtimg.cn`），非官方授权 API，无 SLA，仅供个人使用；天气数据来自 Open-Meteo。商用请替换为授权数据源。