mcp-use README

项目的 README,来自 github.com/Cappybara12/mcp-use。合并为一个 markdown 文件:README.md。

Python ↔ TypeScript with Graftcode: a content-pipeline demo

Graftcode Impact Programme: this project is approved for participation in the Graftcode Impact Programme. A Python service (an article-research-and-drafting pipeline) called directly from a TypeScript dashboard and a Node script through Graftcode, with no REST layer: no FastAPI routes, no Pydantic DTOs, no hand-written fetch client.

 Browser (React) ── generated Graft ── WebSocket ─┐
 Node test script ─ generated Graft ──────────────┤
                                                  ▼
 Claude / Cursor ── MCP over HTTP ──────►  Graftcode Gateway ─► ArticlePipelineService (Python)
                                           :8080 ws · :8081 /mcp   plain public methods

There is no HTTP adapter: the browser imports the generated Graft and talks to the Gateway directly. MCP is the Gateway's built-in endpoint, not a separate bridge.

It was built for Wayzyy's content engine. You do not need that pipeline to run this repo: without it the receiver runs in demo mode on bundled sample data.

How the pieces fit together

Implementation video MCPUSE

The repository has one Python service and several ways to use it. The dashboard and Node client use the generated Graft over WebSocket; MCP-compatible clients use the Gateway's built-in HTTP endpoint. They all reach the same public Python methods.

flowchart LR
    A[React dashboard] -->|generated Graft<br/>WebSocket :8080| G[Graftcode Gateway]
    B[Node.js client] -->|generated Graft<br/>WebSocket :8080| G
    C[Claude / Cursor] -->|MCP over HTTP<br/>/mcp :8081| G
    G --> S[ArticlePipelineService<br/>plain Python methods]
    S --> D[(Topics and drafts)]
    S --> P[Optional real pipeline<br/>research, writing, publishing]

The important boundary is the Python service. The UI, scripts, and AI assistants are clients of the same service rather than separate copies of the content logic.

The content workflow

The demo models an editorial workflow from an idea to a reviewable change. Sources and rules inform the draft, while the human review step remains the publishing gate.

flowchart LR
    I[Topic queue] --> R[RSS and web research]
    I --> K[Keyword research]
    R --> O[Outline]
    K --> O
    B[Existing blog] --> L[Style and rulebook]
    L --> O
    O --> W[Write draft]
    W --> E[SEO and style checks]
    E --> H{Human review}
    H -->|needs changes| W
    H -->|approved| PR[Stage GitHub PR]
    H -->|approved| X[Optional publisher]

The bundled receiver runs this flow in demo mode with sample data. Attaching the real article pipeline replaces the sample sources and placeholder writer with the project's live research, LLM, and publishing integrations.

For the expanded diagrams and demo notes, see docs/architecture.md.

What is real and what is demo

Method With the real pipeline attached Demo mode (default for new users)
getPipelineStatus Real provider/queue status Reports demo mode and sample counts
listPendingTopics, getTopicSources Reads the scanner's review queue Reads receiver/sample_data/review
listDrafts, getDraft, saveDraft Reads/writes the writer's drafts Reads/writes receiver/sample_data/drafts
runStyleCheck Heuristic brand check on the draft text Same
suggestNextArticle Ranks the real queue (keyword tiers + source count) Ranks the sample queue
writeArticle Runs the full LLM research → outline → write pipeline Writes a clearly labelled placeholder draft
runScanner Runs the scanner project's main.py --scan Reports skipped (demo mode)
pushToGithub Opens a real GitHub PR Raises an error (needs the pipeline)

Pipeline Studio

Beyond the original demo, the dashboard includes a visual Pipeline Studio: build a content pipeline from steps (RSS, web research, learn-from-your-blog rules, keyword research, outline, write, SEO check, human review, Reddit ideas, GitHub pull request), run it and watch each step finish, plan content on a calendar by drag and drop, schedule drafts with a GitHub Action, and manage several blogs with their own API keys. It works offline out of the box. See STUDIO.md.

The original dashboard

Open http://localhost:5173 after start.sh. It calls the Python receiver straight from the browser through the generated Graft (WebSocket).

Tab What it exercises
Dashboard getPipelineStatus, listPendingTopics, listDrafts, plus the live "Run topic scanner" and "Suggest next article" actions
Topic Queue listPendingTopics, getTopicSources (the sources modal)
Draft Studio getDraft, saveDraft, writeArticle (Auto-Pilot Draft), runStyleCheck, pushToGithub (Stage PR)
Style Auditor Result of runStyleCheck
Architecture Live benchmark of the same method through the Graft and through MCP, the live MCP tool list, and the known limits

With the real pipeline attached, Auto-Pilot Draft calls LLM APIs, Scan for New Topics calls the search API, and Stage PR can open a real pull request. In demo mode none of these cost anything.

Suggested screenshots

Screenshots are optional, but these four make the project easier to evaluate:

  1. Pipeline overview: Topic Queue, research, drafting, review, and GitHub staging.
  2. Draft Studio: a generated draft beside its style-check result.
  3. Architecture: the Graft/MCP comparison and the available MCP tools.
  4. GitHub staging: the branch and pull-request URL from a test repository.

Place them in docs/images/ and redact API keys, personal access tokens, private URLs, and unpublished customer content.

Client settings (optional): VITE_GRAFT_HOST (default ws://localhost:8080/ws) and VITE_GRAFT_MCP_URL (default http://localhost:8081/mcp).

Prerequisites

Run it

bash scripts/start.sh

This starts the gateway, installs the freshly generated graft package into test-client/ and ui/, runs the Node → Python test, and starts the dashboard at http://localhost:5173. Graft Vision (the gateway's inspector) is at http://localhost:8081.

bash scripts/stop.sh        # stop everything
bash scripts/start.sh --no-ui   # skip the dashboard

Run the Python tests (they use demo mode and need no network or keys):

cd receiver && pip install pytest && python -m pytest

Make it yours: one config file

Everything niche-specific lives in a YAML file, so the same receiver, Graft, MCP tools and dashboard can serve any blog. Copy receiver/config/wayzyy.yaml, edit it, and point PIPELINE_CONFIG at it before starting:

PIPELINE_CONFIG=my-blog.yaml bash scripts/start.sh
Section What it controls
brand Name and description (shown in the dashboard), the topic keyword the style check looks for, the fallback research prompt, and niche / offering / offering_plural, which the article pipeline uses in its prompts and closing call to action (set them, or a new niche inherits Wayzyy's)
categories How queue topics are grouped (first matching keyword rule wins, else default)
suggestion.tiers Which topic keywords the "suggest next article" ranking favours, highest priority first
style Banned words and openers, the attribution keyword (for example a stock-photo site), the publish threshold
data_dir Folder with review/ and drafts/ samples used in demo mode

Keys you leave out fall back to the built-in defaults, and a malformed file stops startup with a clear Config error message. A second, non-travel example is in receiver/config/examples/saas/. Try it with no keys:

PIPELINE_CONFIG=receiver/config/examples/saas/config.yaml \
WAYZYY_WRITER_DIR=/nonexistent WAYZYY_SCANNER_DIR=/nonexistent bash scripts/start.sh

The editorial and editorial_rules sections also let a project owner control the quality contract: minimum length, keyword frequency, required sections, source links, image attribution, human review, tone, required elements, and banned phrases. These rules are injected into the planner/writer prompts and enforced again by the receiver's style audit.

Keyword research for real teams

Pipeline Studio is designed for more than a single blog owner. A ghostwriter, agency, or in-house content team can use one workspace per client and keep that client's voice in the Rulebook, while reusing the same pipeline shape. Keyword research supports four practical modes:

The Keyword research settings let the user choose country and language, filter by search intent, set minimum volume or maximum difficulty, and exclude phrases such as a competitor, location, or irrelevant product. Provider intent is used when available; otherwise Studio makes a small, transparent phrase-based inference. The output reports how many candidates survived and adds the top ten to Content planner. The user then chooses the primary keyword before the outline and writing steps run.

For repeat work, save the configured keyword step or Rulebook as a workspace template. Templates can be exported and imported between client workspaces, but they contain no API keys. Keep the keys in Settings & keys. The Rulebook is the shared quality contract for every client: voice, length, headings, source requirements, FAQ, calls to action, and banned phrases are used in prompts and checked again by SEO. The intended daily flow is:

brief → keyword shortlist → primary keyword → topic → research → rulebook → outline → draft → SEO → human review → PR

This makes the project useful as a client-facing ghostwriting tool as well as a Wayzyy-specific content engine: a user can change the inputs and editorial rules without rewriting the receiver or the Graft/MCP integration.

The site publisher remains an adapter: agent/site_publisher.py currently targets Wayzyy's React/TSX blog shape. To publish to another site, keep the receiver and editorial config but replace that adapter for the target repository, then set PUBLISHER_MODULE and PUBLISHER_FUNCTION in .env. The adapter should return the same fields (slug, branch, commit_hash, files_modified, and message) so the dashboard can show the PR result.

Attach the real pipeline (optional)

If you cloned this as the graftcode/ folder of the mcp-use repo, the real pipeline is the parent folder. Attach it with an absolute path (the gateway runs from a different working directory):

WAYZYY_WRITER_DIR="$(cd .. && pwd)" bash scripts/start.sh

Copy .env.example and export the variables you need, for example WAYZYY_WRITER_DIR, WAYZYY_SCANNER_DIR and WAYZYY_SITE_DIR. The pipeline reads its own LLM and search keys from its own .env; this repo never stores secrets.

Use it from Claude or Cursor (MCP)

The Gateway serves every public receiver method as an MCP tool at http://localhost:8081/mcp (JSON-RPC over HTTP with an Mcp-Session-Id session). Check it from a terminal:

bash scripts/mcp-check.sh

Cursor (.cursor/mcp.json):

{ "mcpServers": { "graft-content-pipeline": { "url": "http://localhost:8081/mcp" } } }

Claude Desktop only speaks stdio, so bridge the endpoint with mcp-remote:

{
  "mcpServers": {
    "graft-content-pipeline": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:8081/mcp"]
    }
  }
}

The Pipeline Studio adds studio_* tools; studio_write_article and studio_decide write and approve an article in one call each (see STUDIO.md).

MCP tool names are the Python method names (suggest_next_article, write_article, ...). Results come back as JSON text. The earlier hand-written FastMCP bridge is kept in legacy/ as a "before" comparison only.

Verify it yourself

Layout

receiver/article_receiver/service.py   the Python receiver (plain class, public methods)
receiver/config/                       default config and a non-travel example
receiver/sample_data/                  demo-mode topics and drafts
receiver/tests/                        pytest suite
scripts/                               start.sh, stop.sh, run_gateway.sh, mcp-check.sh
test-client/                           Node script calling the receiver through the graft
ui/                                    Vite + React dashboard (calls the Gateway directly)
legacy/                                the superseded FastMCP bridge (comparison only)

Notes and limitations

License

MIT. The Graftcode gateway (gg) and the generated Graft packages are Graftcode's own software and are governed by their terms; this repository does not redistribute them.

mcp-use (Cappybara12/mcp-use)

正在搜索数据库…

这是什么?这是一个演示仓库:一个 Python 内容流水线服务通过 Graftcode 被 TypeScript 仪表盘和一个 Node 脚本直接调用,中间没有 REST 层。
这是库还是独立应用?这是一个可以直接运行的演示,而不是库:包括一个 Python 接收端、一个仪表盘和一个 Node 客户端,它们都通过 Graftcode Gateway 连接在一起。
怎么让它跑起来?安装 Python 3.10+ 和 Node 18+,运行 'pip install -r receiver/requirements.txt',然后用 start.sh 启动整套服务。如果没有接入真实的流水线,接收端会以演示模式运行,使用内置的示例数据,因此不需要任何密钥。
开始之前需要准备什么?Python 3.10+、Node 18+、用于读取配置文件的 PyYAML,以及 Graftcode Gateway(gg)。只有接入真实的文章流水线时才需要 API 密钥。
有哪些需要注意的限制?Gateway 没有身份验证,包括 /mcp 端点也是如此;配置后,pushToGithub 可以真正发起拉取请求。对象类型的结果会以 JSON 字符串返回,而不是带类型的对象。
我能把它用在自己的博客或客户项目上吗?可以。复制 YAML 配置文件,修改品牌、细分领域和风格规则,然后让 PIPELINECONFIG 指向它。站点发布适配器仍然针对 Wayzyy 的 React/TSX 博客结构,因此用于其他网站时可能需要替换它。
它会把我的数据发送到别处吗?演示模式只使用内置的示例数据。接入真实流水线后,撰写内容会调用大语言模型 API,选题扫描会调用搜索 API,因此你的内容和密钥会发送给这些服务商。
仪表盘和 Node 客户端如何调用 Python 代码?通过 Graftcode Gateway。它们使用生成的 Graft 包,基于 WebSocket 通信,因此不需要手写 fetch 客户端或 REST 路由。
Claude 或 Cursor 能把它当作工具使用吗?可以。Gateway 会把每个公开的接收端方法通过 HTTP 作为 MCP 工具提供出来,因此 Cursor 可以通过 .cursor/mcp.json 连接,Claude Desktop 则可以借助 mcp-remote 进行桥接。
什么是 Pipeline Studio?它是仪表盘中的一个可视化构建器,你可以把 RSS、关键词研究、大纲、撰写、SEO 检查、人工审核等步骤串联起来,然后运行并查看每一步的完成情况。
它会自动发布吗?不会。人工审核步骤始终是发布的关卡,质量审计只会标记问题,由人来决定如何处理。
大小
132.4 MB
星标
1K
更新
提交Nov 10
时长
3个月
提交 · 90 天