NTeALan dictionaries MCP Server is a modular, extensible Model Context Protocol (MCP) server for NTeALan REST APIs dictionaries and contributions. This project provides a unified interface for managing dictionary data, articles, and user contributions, and is designed for easy integration and extension.

The project is deployed at https://apis.ntealan.net/ntealan/mcpserver. Add /sse path to connect to a MCP client. Only resource actions can be used now.

⚠️ This dev endpoint could be unavailable sometimes. Just create an issue and we will work on it.

---

🦜 Table of Contents

• Features
• Getting Started
  • Prerequisites
  • Installation
  • Running the Server
• Project Structure
• Usage
  • Resources
  • Tools
• Contributing
• Contact

---

🦜 Features

• Dictionary Management: Create, update, delete, and retrieve dictionaries and their metadata.
• Article Management: Manage articles within dictionaries, including statistics and filtering.
• Contribution Management: Track and manage user contributions to articles and dictionaries.
• Extensible MCP Server: Easily add new resources and tools.
• Async Support: Built on top of fastmcp and aiohttp for high performance.
• OpenAPI-like Resource Registration: Register resources and tools with URIs and tags.

---

🦜 Getting Started

Prerequisites

• Python 3.11+
• uv
• aiohttp
• pydantic
• fastmcp (or your fork)
• aiodns
• python-dotenv

Installation

Installing via pip

Clone the repository and install dependencies:

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

(Optional) Install and use uv for faster dependency management

If you want faster installs and modern Python packaging, you can use uv in the ntealan-apis-mcp-server directory:

uv sync

Running the Server

To start the MCP server:

python -m ntealanmcp -t stdio

Or, if you have uv installed, you can run server command:

ntealanmcp -t stdio

The server will run using the Server-Sent Events (sse) transport by default at this endpoint http://127.0.0.1:8000/sse. You can modify the transport in main.py if needed.

---

🦜 Project Structure

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

---

🦜 Usage

Primitive resources

Resources are asynchronous functions that expose public Data from NTeALan API endpoints for dictionaries, articles, and contributions. They are registered with the MCP server and can be called via their custom URIs.

Example resource registration:

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}!"}

List of existings resources and status:

Name / URI Pattern	Description	Parameters	Development Status
ntealan-apis://dictionaries/dictionary/{dictionary_id}	Get dictionary metadata by ID	dictionary_id	Stable
ntealan-apis://dictionaries?limit=2	Get all dictionaries metadata	limit	Stable
ntealan-apis://dictionaries/statistics/{dictionary_id}	Get statistics for a specific dictionary	dictionary_id	Stable
ntealan-apis://dictionaries/statistics	Get statistics for all dictionaries	None	Stable
ntealan-apis://articles/dictionary/{dictionary_id}/{article_id}?none	Get article by ID	dictionary_id, article_id	Stable
ntealan-apis://articles?limit=2	Get all articles	limit	Stable
ntealan-apis://articles/dictionary/{dictionary_id}?limit=2	Get all articles for a dictionary	dictionary_id, limit	Stable
ntealan-apis://articles/statistics/{dictionary_id}	Get article statistics for a dictionary	dictionary_id	Stable
ntealan-apis://articles/statistics	Get statistics for all articles	None	Not stable
ntealan-apis://contributions/{dictionary_id}/{contribution_id}	Get contribution by ID	dictionary_id, contribution_id	Stable
ntealan-apis://greeting/Elvis	Greeting resource	name	Stable
ntealan-apis://articles/dictionaries/search/{dictionary_id}?q=mba&page=1&limit=1	Search articles in a dictionary	dictionary_id, q, page, limit	Stable
ntealan-apis://articles/search?q=mba&page=1	Search articles	q, page	Stable
ntealan-apis://dictionaries/search?q=yemb&page=1&limit=1	Search dictionaries	q, page, limit	Stable

Primitive tools

Tools are utility functions for creating, updating, and deleting dictionaries, articles, and contributions.

Example tool registration:

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

List of existings tools and status (NOT YET IMPLEMENTED):

Tool Name	Description	Required Payload Fields	Development Status
create_dictionary	Create a new dictionary	data (dictionary fields)	Not started
update_dictionary	Update an existing dictionary	dictionary_id, data (fields to update)	Not started
delete_dictionary	Delete a dictionary	dictionary_id	Not started
create_article	Create a new article	dictionary_id, data (article fields)	Not started
update_article	Update an article	dictionary_id, article_id, data (fields to update)	Not started
delete_article	Delete an article	dictionary_id, article_id	Not started
create_contribution	Create a new contribution	dictionary_id, article_id, data (contribution fields)	Not started
update_contribution	Update a contribution	dictionary_id, article_id, contribution_id, data	Not started
delete_contribution	Delete a contribution	dictionary_id, article_id, contribution_id	Not started

Run examples

Check examples/ folder to run and test some samples.

# 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

You can get docs on :

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

Deploying with Docker

You can deploy the MCP server using Docker and serve it behind an Nginx reverse proxy for production environments.

1. Build the Docker image

Build the Docker image manually:

docker build -t ntealan-mcp-server .

2. Or automatically build and start the service

• Get and check the latest version of compose and Docker. You will get in response Docker Compose version v2.35.1.

docker compose version

• Build and start the service

docker compose up --build -d

• Your MCP server will now be accessible at this address http://0.0.0.0:8000 or your configured domain.

• Connect with MCP Client at http://127.0.0.1:8000/sse or your configured domain.

Connect with Smithery

• Install mcp cli

uv add "mcp[cli]"

• Connect with MCP client

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())

---

🦜 Contributing

Get more informations in this file: CONTRIBUTION.md

🦜 Contact

• Project Lead: Elvis Mboning@NTeALan
• NTeALan APIs documentation: https://apis.ntealan.net/ntealan
• GitHub Issues: https://github.com/Levis0045/ntealan-apis-mcp-server/issues
• Email: contact@ntealan.org