Ntealan Apis Mcp Server

---

🦜 目次

• 機能
• はじめに
  • 前提条件
  • インストール
  • サーバーの起動
• プロジェクト構成
• 使い方
  • リソース
  • ツール
• 貢献
• お問い合わせ

---

🦜 機能

• 辞書管理：辞書とそのメタデータの作成、更新、削除、取得ができます。
• 記事管理：統計情報やフィルタリングなど、辞書内の記事を管理できます。
• 貢献の管理：記事や辞書へのユーザーの貢献を追跡・管理できます。
• 拡張可能な MCP サーバー：新しいリソースやツールを簡単に追加できます。
• 非同期処理のサポート：fastmcpとaiohttpを基盤として構築されており、高いパフォーマンスを実現します。
• OpenAPI 風のリソース登録：URI とタグを指定してリソースやツールを登録できます。

---

🦜 はじめに

前提条件

• Python 3.11+
• uv
• aiohttp
• pydantic
• fastmcp（またはそのフォーク）
• aiodns
• python-dotenv

インストール

pip を使ったインストール

リポジトリをクローンし、依存関係をインストールします。

git clone https://github.com/Levis0045/ntealan-apis-mcp-server.git
cd ntealan-apis-mcp-server
pip install .

（任意）依存関係をより速く管理するためにuvをインストールして使用する

インストールを高速化し、最新の Python パッケージ管理を利用する場合は、ntealan-apis-mcp-serverディレクトリでuvを使用できます。

uv sync

サーバーの起動

MCP サーバーを起動するには：

python -m ntealanmcp -t stdio

または、uvがインストールされている場合は、次のサーバーコマンドを実行できます。

ntealanmcp -t stdio

サーバーは、デフォルトでこのエンドポイントhttp://127.0.0.1:8000/sseにてServer-Sent Events (sse)トランスポートを使用して起動します。必要に応じて、main.pyでトランスポートを変更できます。

---

🦜 プロジェクト構成

ntealan-api/
├── src/
│   └── ntealan_apis_mcp/
│       ├── main.py
│       ├── models/
│       │   ├── article.py
│       │   ├── contribution.py
│       │   ├── dictionary.py
│       │   └── common.py
│       ├── primitives/
│       |    ├── resources/
│       │    │   ├── article.py
│       │    │   ├── contribution.py
│       │    │   └── dictionary.py
│       |    └── tools/
│       |        ├── article.py
│       |        ├── contribution.py
│       |        └── dictionary.py
│       └── common/
│           ├── utils.py
│           ├── cache.py
│           └── http_session.py
├── examples/
├── tests/
├── pyproject.toml
└── requirements.txt

---

🦜 使い方

プリミティブリソース

リソースは、辞書、記事、投稿に関する NTeALan API エンドポイントの公開データを提供する非同期関数です。MCP サーバーに登録され、独自の URI から呼び出すことができます。

リソース登録の例：

ntl_mcp_server.add_resource_fn(
    lambda dictionary_id, article_id, params: get_article_by_id(
        dictionary_id, article_id, params, ntl_mcp_server.get_context()
    ),
    name="get_article_by_id",
    uri="ntealan-apis://articles/dictionary/{dictionary_id}/{article_id}?{params}",
    tags=["article-endpoint", "mcp-resource"],
    mime_type="application/json",
    description="Get an article by ID"
)

# or just use the classic integration
@ntl_mcp_server.resource(
    uri="ntealan-apis://articles/dictionary/{dictionary_id}/{article_id}?{params}",
    tags=["article-endpoint", "mcp-resource"],
    mime_type="application/json"
)
async def get_article_by_id(
    dictionary_id: str, article_id: UUID,
    params: str, ctx: Context
) -> McpResourceResponse:
    """
    Retrieve a article by its unique identifier.
    """
    # Placeholder logic
    return {"status": "OK", "data": f"Hello, {article_id}!"}

既存リソースの一覧とステータス：

名前 / URI パターン	説明	パラメーター	開発ステータス
ntealan-apis://dictionaries/dictionary/{dictionary_id}	ID で辞書のメタデータを取得	dictionary_id	安定
ntealan-apis://dictionaries?limit=2	すべての辞書のメタデータを取得	limit	安定
ntealan-apis://dictionaries/statistics/{dictionary_id}	特定の辞書の統計情報を取得	dictionary_id	安定
ntealan-apis://dictionaries/statistics	すべての辞書の統計情報を取得	なし	安定
ntealan-apis://articles/dictionary/{dictionary_id}/{article_id}?none	ID で記事を取得	dictionary_id、article_id	安定
ntealan-apis://articles?limit=2	すべての記事を取得	limit	安定
ntealan-apis://articles/dictionary/{dictionary_id}?limit=2	辞書のすべての記事を取得	dictionary_id、limit	安定
ntealan-apis://articles/statistics/{dictionary_id}	辞書の記事の統計情報を取得	dictionary_id	安定
ntealan-apis://articles/statistics	すべての記事の統計情報を取得	なし	不安定
ntealan-apis://contributions/{dictionary_id}/{contribution_id}	ID で投稿を取得	dictionary_id、contribution_id	安定
ntealan-apis://greeting/Elvis	あいさつリソース	name	安定
ntealan-apis://articles/dictionaries/search/{dictionary_id}?q=mba&page=1&limit=1	辞書内の記事を検索	dictionary_id、q、page、limit	安定
ntealan-apis://articles/search?q=mba&page=1	記事を検索	q、page	安定
ntealan-apis://dictionaries/search?q=yemb&page=1&limit=1	辞書を検索	q、page、limit	安定

プリミティブツール

ツールは、辞書、記事、投稿を作成、更新、削除するためのユーティリティ関数です。

ツール登録の例：

ntl_mcp_server.add_tool(
    create_dictionary,
    description="Create a new dictionary",
    tags=["mcp-tool", "dictionary-endpoint"]
)

既存のツールとステータスの一覧（未実装）：

ツール名	説明	必須のペイロードフィールド	開発ステータス
create_dictionary	新しい辞書を作成します	data（辞書のフィールド）	未着手
update_dictionary	既存の辞書を更新します	dictionary_id、data（更新するフィールド）	未着手
delete_dictionary	辞書を削除します	dictionary_id	未着手
create_article	新しい記事を作成します	dictionary_id、data（記事のフィールド）	未着手
update_article	記事を更新します	dictionary_id、article_id、data（更新するフィールド）	未着手
delete_article	記事を削除します	dictionary_id、article_id	未着手
create_contribution	新しい投稿を作成します	dictionary_id、article_id、data（投稿のフィールド）	未着手
update_contribution	投稿を更新します	dictionary_id、article_id、contribution_id、data	未着手
delete_contribution	投稿を削除します	dictionary_id、article_id、contribution_id	未着手

実行例

サンプルを実行してテストするには、examples/ フォルダーを確認してください。

# for all resources
uv run examples/run_client_resources.py -t sse -e prod -s 8
# for all tools
uv run examples/run_client_tools.py -t stdio -e local -s 0

ドキュメントはこちらで確認できます：

# for all resources
uv run examples/run_client_resources.py -h
# for all tools
uv run examples/run_client_tools.py -h

Docker を使用したデプロイ

Docker を使用して MCP サーバーをデプロイし、本番環境では Nginx リバースプロキシの背後で提供できます。

1. Docker イメージをビルドする

Docker イメージを手動でビルドします：

docker build -t ntealan-mcp-server .

2. または、サービスを自動的にビルドして起動する

• 最新バージョンの Compose と Docker を取得して確認します。応答として Docker Compose version v2.35.1 が表示されます。

docker compose version

• サービスをビルドして起動します

docker compose up --build -d

• MCP サーバーは、http://0.0.0.0:8000 または設定したドメインでアクセスできるようになります。

• MCP クライアントを http://127.0.0.1:8000/sse または設定したドメインに接続します。

Smithery に接続する

• mcp CLI をインストールします

uv add "mcp[cli]"

• MCP クライアントを接続します

import mcp
from mcp.client.websocket import websocket_client
import json
import base64

smithery_api_key = "your-api-key"
url = f"wss://server.smithery.ai/@Levis0045/ntealan-apis-mcp-server/ws?api_key={smithery_api_key}"

async def main():
    # Connect to the server using websocket client
    async with websocket_client(url) as streams:
        async with mcp.ClientSession(*streams) as session:
            # Initialize the connection
            await session.initialize()
            # List available tools
            tools_result = await session.list_tools()
            print(f"Available tools: {', '.join([t.name for t in tools_result.tools])}")

            # Example of calling a tool:
            # result = await session.call_tool("tool-name", arguments={"arg1": "value"})

if __name__ == "__main__":
    import asyncio
    asyncio.run(main())

---

🦜 コントリビューション

詳しくは、こちらのファイルをご覧ください：CONTRIBUTION.md

🦜 お問い合わせ

• プロジェクトリード：Elvis Mboning@NTeALan
• NTeALan API ドキュメント：https://apis.ntealan.net/ntealan
• GitHub の課題：https://github.com/Levis0045/ntealan-apis-mcp-server/issues
• メール：[email protected]