Skip to main content
Glama
deenesjakoruzh
vigilancetrent

mcpforge

by vigilancetrent
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

mcpforge

5줄의 파이썬 코드로 MCP 서버를 배포하세요.

Python License: MIT Status MCP

Before                              After
──────                              ─────
~200 lines of                       @serve
JSON-RPC stdio                      class MarketTools:
boilerplate, schema                     @tool
generation, error                       def latest_price(self, symbol: str) -> float: ...
handling, lifecycle                     @tool
management.                             def search(self, query: str) -> list[dict]: ...

                                    $ python -m mcpforge run market:MarketTools
                                    ✓ MCP server running on stdio

mcpforge를 사용하는 이유

MCP(Model Context Protocol)는 Claude, Cursor 및 급성장하는 AI 도구 생태계에서 외부 함수를 호출하기 위해 사용하는 오픈 표준입니다. 강력하지만, 서버를 작성하는 과정은 현재 매우 번거롭습니다.

모든 프로젝트에서 동일한 JSON-RPC 프레이밍, 스키마 생성, 디스패치 루프, 오류 처리를 반복해서 작성해야 합니다. mcpforge는 이 모든 것을 제거합니다. 클래스에 어노테이션을 달고, 메서드에 타입 힌트를 추가하기만 하면 끝입니다.

from mcpforge import serve, tool

@serve(name="market_tools", version="0.1.0")
class MarketTools:
    """Market data tools for AI agents."""

    @tool(description="Get the latest price for a symbol")
    def latest_price(self, symbol: str) -> float:
        return fetch_price(symbol)

    @tool
    def search(self, query: str, limit: int = 10) -> list[dict]:
        """Search ticker symbols matching `query`."""
        return run_search(query, limit)

이것으로 사양을 완벽하게 준수하는 MCP 서버가 완성됩니다. 타입 힌트는 JSON 스키마가 되고, 독스트링은 도구 설명이 되며, 반환값은 자동으로 직렬화됩니다.

Related MCP server: nbmcp

60초 퀵스타트

pip install mcpforge
# hello.py
from mcpforge import serve, tool

@serve(name="hello", version="0.1.0")
class HelloTools:
    @tool
    def greet(self, name: str = "world") -> str:
        """Say hello to someone."""
        return f"Hello, {name}!"
python -m mcpforge run hello:HelloTools

이제 stdio를 통해 JSON-RPC 2.0으로 통신하는 작동 가능한 MCP 서버가 준비되었습니다.

작동 원리

  1. @serve는 클래스를 MCP 서버(이름, 버전, 기능)로 태그합니다.

  2. @tool은 메서드를 MCP 도구로 등록합니다.

  3. @resource(uri=...)는 메서드를 MCP 리소스로 등록합니다.

  4. mcpforge는 각 메서드의 시그니처를 분석하여 JSON 스키마를 생성합니다. 기본 타입, list[T], dict[str, T], Literal[...], Optional[T], 데이터 클래스 및 Pydantic 모델 모두 그대로 작동합니다.

  5. python -m mcpforge run mod:Class는 stdio 루프를 부팅하고, initialize / tools/list / tools/call / resources/list / resources/read를 처리하며, 적절한 코드로 JSON-RPC 오류를 보고합니다.

외부 MCP SDK가 필요 없습니다. 스키마 편의를 위해 표준 라이브러리 json과 pydantic만 사용합니다.

내장 서버

오늘 바로 사용할 수 있는 두 가지 기본 제공 서버입니다:

# Filesystem tools (sandboxed to a root directory)
python -m mcpforge run mcpforge.builtin.filesystem:FilesystemTools

# HTTP fetch tools
python -m mcpforge run mcpforge.builtin.http:HttpTools

FilesystemTools는 경로 탐색 검사가 포함된 샌드박스 환경에서 list_dir, read_file, search를 제공합니다. HttpTools는 크기 제한이 있는 fetch_url을 제공합니다.

Claude Desktop에 연결

~/Library/Application Support/Claude/claude_desktop_config.json에 추가하세요:

{
  "mcpServers": {
    "market": {
      "command": "python",
      "args": ["-m", "mcpforge", "run", "market:MarketTools"],
      "cwd": "/path/to/your/project"
    }
  }
}

Claude Desktop을 재시작하면 대화창에 도구가 나타납니다.

Cursor에 연결

~/.cursor/mcp.json:

{
  "mcpServers": {
    "market": {
      "command": "python",
      "args": ["-m", "mcpforge", "run", "market:MarketTools"]
    }
  }
}

비교

기능

mcpforge

mcp SDK

FastMCP

직접 구현

단일 데코레이터

예

아니오

예

아니오

타입 기반 자동 JSON 스키마

예

아니오

예

아니오

Pydantic v2 지원

예

예

예

아니오

pyd 외 추가 의존성 없음

예

아니오

아니오

N/A

내장 fs / http 서버

예

아니오

아니오

아니오

헬로 월드 코드 라인 수

~5

~40

~10

~200

와이어 형식 검사

python -m mcpforge inspect market:MarketTools

클라이언트가 보게 될 정확한 tools/list 페이로드를 출력합니다.

로드맵

  • [x] 도구 (호출, 목록)

  • [x] 리소스 (읽기, 목록)

  • [x] 타입 힌트 -> JSON 스키마 (Pydantic v2, 데이터 클래스, Literal, Optional)

  • [x] 내장 파일 시스템 및 http 서버

  • [ ] 리소스 구독

  • [ ] 프롬프트 기능

  • [ ] 샘플링 기능

  • [ ] WebSocket / HTTP-SSE 전송 (선택적 [http] 추가)

  • [ ] 비동기 도구 (async def)

  • [ ] OTel 추적 훅

라이선스

MIT — LICENSE를 참조하세요.

작성자: thechifura. quantflow 및 strategos의 형제 프로젝트입니다.

Available Tools

3 tools
list_dirA

List entries in path (relative to the sandbox root).

ParametersJSON Schema
NameRequiredDescriptionDefault
pathNo.

TDQS

A3.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description bears full burden. It does not disclose what types of entries are listed (files, directories), sorting order, or any other behavioral traits beyond listing.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence with no wasted words. Verb is front-loaded, and the essential context is included efficiently.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple listing tool with one parameter and no output schema, the description is adequate but could be more complete by noting whether entries include both files and directories.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema has 0% description coverage, but description adds meaning by specifying that path is relative to the sandbox root. This clarifies a key detail not in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the verb 'list', the resource 'entries in path', and adds context 'relative to the sandbox root'. It distinguishes from sibling tools read_file and search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives or exclusions. The description does not mention any context or conditions for usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

read_fileA

Read up to max_bytes bytes of the file at path as UTF-8 text.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYes
max_bytesNo

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses that it reads up to max_bytes as UTF-8 text, but does not mention error behavior (e.g., file not found, binary files) or performance implications. With no annotations, the description provides moderate transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, clear sentence that efficiently covers the tool's core functionality without extraneous words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and sibling tools, the description could mention return value format or error handling. It adequately covers the main behavior but lacks completeness for a file reading tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It explains both parameters: path is the file location, max_bytes limits the bytes read, and specifies UTF-8 encoding. However, it does not clarify path format (absolute/relative).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it reads a file at a given path, up to a specified number of bytes, as UTF-8 text. It distinguishes from sibling tools 'list_dir' (listing directory contents) and 'search' (searching for files).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. There is no mention of when not to use it or any prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv0.1.0
    • First observedlist_dir
    • First observedread_file
    • First observedsearch
Deploy Server
Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

TDQS

B3.3/5.0

Scored across 3 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: listing directory entries, reading file contents, and searching for patterns. No overlap in functionality.

Naming Consistency4/5

Naming is mainly verb_noun (list_dir, read_file) with one tool using a single verb (search). All use consistent snake_case, but slight pattern deviation prevents a perfect score.

Tool Count5/5

Three tools is a reasonable and focused set for basic file operations within a sandbox. Each tool serves a distinct and necessary function.

Completeness2/5

Only read-only operations are provided. Missing write, update, or delete tools, which are essential for a file manipulation server, leaving significant gaps.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • cleanmcp

    Lishang25
    F
    license
    Not graded
    quality
    D
    maintenance
    A MCP server framework with zero-config auto-discovery, type-safe decorators, and HTTP transport, enabling easy creation and deployment of tools, prompts, and resources to LeanMCP Cloud.
    -

  • nbmcp

    rum1887
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables building lightweight MCP servers where Rust handles transport, routing, and schema validation while Python defines tool behavior using type hints, with support for stdio and HTTP transports.
    MIT

  • mcp-forge

    benni-os
    A
    license
    Not graded
    quality
    B
    maintenance
    A FastAPI-style framework for building MCP servers in Python, enabling declarative tool definitions with automatic schema validation and multiple transport options.
    MIT

  • nn-mcp-stdio

    fre-sch
    A
    license
    Not graded
    quality
    B
    maintenance
    A no-nonsense framework for building stdio MCP servers using plain async handlers and type annotations, with strict schema validation and no configuration overhead.
    MIT