TIB MCP
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-versionfile for tool compatibility - uv — used as the package manager, build system, and script runner
Quick Start```bash
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:```bash
uv run python main.py
For example, to configure this server in an MCP client, point it at:```json
{
"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:```bash
# 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:```bash
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:```bash
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:```bash
Build the image
docker build -t tib-mcp .
Run the container
docker run -p 8000:8000 tib-mcp
Override configuration with environment variables:```bash
docker run -e MCP_LOG_LEVEL=DEBUG -p 8000:8000 tib-mcp
Running Tests```bash
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:```bash
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:```bash
uv run pre-commit install
This runs automatically on every commit, or manually with:```bash
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`:```python
class MyToolService:
def do_something(self, param: str) -> str:
return param.strip().upper()
- Export the service in
server/services/__init__.py:```python
from server.services.my_tool import MyToolService
all = ["SumService", "MyToolService"]
3. **Create the MCP tool sub-server** in `server/tools/my_tool.py`:```python
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.
- Mount the tool in
server/tools/__init__.py:```python
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:```bash
uv run pytest
uv run pre-commit run --all-files
License
This project is licensed under the MIT License. © 2026 ORKG/TIB Team
