TIB Server

A Model Context Protocol (MCP) server for scholarly tools, built with FastMCP. MCP is an open standard that lets AI assistants interact with external tools and data sources through a unified protocol. This server exposes scholarly tools that any MCP-compatible client can discover and invoke.

Prerequisites

• Python 3.14+ — the project includes a .python-version file for tool compatibility
• uv — used as the package manager, build system, and script runner

Quick Start

# Clone the repository
git clone https://gitlab.com/TIBHannover/orkg/tib-aissistant/tib-mcp.git
cd tib-mcp

# Create your local environment file
cp .env.example .env

# Install all dependencies (including dev tools)
uv sync

# Start the server
uv run python main.py

By default the server starts in streamable-http mode, which is suitable for networked or remote access. For local MCP client integrations (e.g. Claude Desktop, VS Code with Copilot), you can switch to stdio mode.

Architecture

The runtime is split into small layers:

• main.py and server/main.py are entry points that start the FastMCP server.
• server/app.py builds the application instance (create_app) and registers tools.
• server/core/ contains environment-based configuration (Settings, transport normalization).
• server/tools/ exposes MCP tools and mounts them by namespace.
• server/services/ contains business logic used by tools.
• server/utils/ contains runtime helpers (for example transport-specific run kwargs).

Configuration

All configuration is done through environment variables. A .env file in the project root is automatically loaded on startup via python-dotenv. See .env.example for a documented template.

Variable	Description	Default	Valid Values
MCP_SERVER_NAME	Server Name	TIB MCP Server	any name
MCP_TRANSPORT	Transport protocol	streamable-http	stdio, http, sse, streamable-http
MCP_HOST	Bind address (non-stdio transports)	127.0.0.1	Any valid host/IP
MCP_PORT	Port number (non-stdio transports)	8000	Any valid port
MCP_LOG_LEVEL	Logging verbosity	INFO	DEBUG, INFO, WARNING, ERROR, CRITICAL

Running the Server

stdio Mode

Designed for direct integration with AI clients. The client launches the server as a subprocess and communicates over stdin/stdout:

uv run python main.py

For example, to configure this server in an MCP client, point it at:

{
  "mcpServers": {
    "tib-mcp": {
      "command": "uv",
      "args": ["run", "python", "main.py"],
      "cwd": "/path/to/tib-mcp"
    }
  }
}

HTTP Mode

For networked or remote access, use the streamable-http transport:

# Via .env file
MCP_TRANSPORT=streamable-http

# Or inline
MCP_TRANSPORT=streamable-http uv run python main.py

The server will be available at http://127.0.0.1:8000/mcp.

Try It with MCP Inspector

You can play around with the server using @modelcontextprotocol/inspector:

# Inspect via stdio (launches this server as a subprocess)
npx @modelcontextprotocol/inspector uv run python main.py

If your server is already running in streamable-http mode:

npx @modelcontextprotocol/inspector

Then connect to http://127.0.0.1:8000/mcp from the Inspector UI.

Docker

The project includes a production-ready Dockerfile that defaults to streamable-http transport on 0.0.0.0:8000:

# Build the image
docker build -t tib-mcp .

# Run the container
docker run -p 8000:8000 tib-mcp

Override configuration with environment variables:

docker run -e MCP_LOG_LEVEL=DEBUG -p 8000:8000 tib-mcp

Running Tests

uv run pytest

The test suite is organized into four categories:

Category	Location	Description
Unit	tests/tools/test_sum.py	Direct function-level tests for each tool
Config	tests/test_config.py	Validates environment variable defaults and overrides
Contract	tests/test_contract.py	Verifies tool metadata, descriptions, and JSON schemas
Integration	tests/test_integration.py	End-to-end MCP client/server communication tests

For verbose output:

uv run pytest -v

Project Structure

tib-mcp/
├── main.py                   # Root entry point for running the MCP server
├── server/
│   ├── __init__.py
│   ├── app.py                # App factory (create_app / get_application)
│   ├── main.py               # Server module entry point + exported runtime constants
│   ├── core/
│   │   ├── __init__.py
│   │   └── config.py         # Environment config + transport normalization
│   ├── services/
│   │   ├── __init__.py
│   │   └── sum.py            # Sum service logic
│   ├── tools/
│   │   ├── __init__.py       # Tool mounting (register_tools)
│   │   └── sum.py            # Sum MCP sub-server and tool definition
│   └── utils/
│       ├── __init__.py
│       └── runtime.py        # Runtime helpers (run kwargs per transport)
├── tests/
│   ├── __init__.py
│   ├── conftest.py           # Shared fixtures (mcp_app, mcp_client)
│   ├── test_config.py        # Configuration behavior tests
│   ├── test_contract.py      # Tool metadata/schema contract tests
│   ├── test_integration.py   # MCP client/server integration tests
│   └── tools/
│       ├── __init__.py
│       └── test_sum.py       # Unit tests for sum behavior
├── pyproject.toml            # Dependencies + tool configuration
├── uv.lock                   # Dependency lock file
├── Dockerfile                # Container image definition
├── .dockerignore
├── .env.example              # Environment variable template
├── .pre-commit-config.yaml   # Pre-commit hooks (Ruff + checks)
├── AGENTS.md                 # Repository instructions for coding agents
├── CLAUDE.md
├── LICENSE
└── README.md

Development

Pre-commit Hooks

The project uses Ruff for linting and formatting, configured via pre-commit:

uv run pre-commit install

This runs automatically on every commit, or manually with:

uv run pre-commit run --all-files

Adding a New Tool

Tools in this project follow the same pattern as sum: a service layer for logic, and a FastMCP sub-server for exposure.

1. Create the service in server/services/my_tool.py:

class MyToolService:
    def do_something(self, param: str) -> str:
        return param.strip().upper()

2. Export the service in server/services/__init__.py:

from server.services.my_tool import MyToolService

__all__ = ["SumService", "MyToolService"]

3. Create the MCP tool sub-server in server/tools/my_tool.py:

from fastmcp import FastMCP

from server.services import MyToolService

server = FastMCP("my_tool")
my_tool_service = MyToolService()


@server.tool()
def do_something(param: str) -> str:
    """Short description of what this tool does.

    Args:
        param: Description of the parameter.

    Returns:
        Description of the return value.
    """
    return my_tool_service.do_something(param)

Type hints define the input schema, and the docstring is exposed to MCP clients as tool description.

4. Mount the tool in server/tools/__init__.py:

from fastmcp import FastMCP

from server.tools.my_tool import server as my_tool_server
from server.tools.sum import server as sum_server


def register_tools(app: FastMCP) -> None:
    app.mount(sum_server, namespace="sum")
    app.mount(my_tool_server, namespace="my_tool")

With namespace mounting, this tool is discoverable as my_tool_do_something.

5. Add/update tests:

• Unit test in tests/tools/test_my_tool.py (direct function/service behavior).
• Contract test in tests/test_contract.py (tool name, description, schema, tool count).
• Integration test in tests/test_integration.py (call the tool via MCP client).

Then run:

uv run pytest
uv run pre-commit run --all-files

License

This project is licensed under the MIT License. © 2026 ORKG/TIB Team