Content
# 🧠 one-mcp
## 🚀 Overview
**one-mcp** is a lightweight **MCP (Model Context Protocol)** server built using **FastAPI** that enables intelligent tool management and semantic search for APIs.
It allows you to upload, manage, and query API tools using natural language — powered by modern embedding models via `sentence-transformers`.
The server supports multiple transport modes (stdio, HTTP, or both) and provides both a REST API and MCP tool interface for maximum flexibility.
---
## ✨ Features
* 🔍 **Semantic Search:** Find relevant API tools based on descriptive queries using sentence-transformers embeddings.
* 📤 **Upload Tools:** Add new API tools via JSON body or file upload.
* 🗑️ **Delete Tools:** Remove specific tools by name (supports batch deletion).
* 🧾 **Tool Statistics:** Get insights on stored tools including count, model, and storage path.
* 🧹 **Tool Management:** Clear, inspect, or modify your tool store easily.
* ⚡ **FastAPI Backend:** High-performance, async-ready backend server.
* 🤝 **MCP Compatibility:** Dual interface - REST API and MCP tools for seamless integration.
* 🔄 **Dual Transport:** Support for stdio and HTTP transports simultaneously.
* 💾 **Persistent Storage:** Tools and embeddings saved to disk with automatic loading.
* 📊 **Structured Logging:** Comprehensive logging with rotating file handlers.
---
## 🧩 Project Structure
```
one-mcp/
├── server.py # Main application entry point with server orchestration
├── mcp_server.py # MCP server class with multi-transport support
├── api.py # FastAPI routes and REST endpoints
├── mcp_tools.py # MCP tool definitions and handlers
├── models.py # Pydantic models for request/response validation
├── tools_store.py # Persistent tool storage with embeddings
├── config.py # Server configuration and argument parsing
├── logging_setup.py # Centralized logging configuration
├── test_specs.json # Sample tool dataset for testing
├── CURLS.md # Example cURL commands for testing API endpoints
├── MCP_TOOLS.md # MCP tools documentation
├── requirements.txt # Project dependencies
├── Dockerfile # Docker containerization (CPU-based dependencies)
└── README.md # Project documentation (this file)
```
---
## ⚙️ Installation
### 1. Clone the Repository
```bash
git clone https://github.com/freakynit/one-mcp.git
cd one-mcp
```
### 2. Set Up Virtual Environment
```bash
python -m venv venv
source venv/bin/activate # macOS/Linux
venv\Scripts\activate # Windows
```
### 3. Install Dependencies
```bash
pip install -r requirements.txt
```
Dependencies include:
```
fastapi>=0.104.0
uvicorn>=0.24.0
fastmcp>=0.2.0
python-multipart>=0.0.6
torch==2.4.1
torchvision==0.19.1
torchaudio==2.4.1
sentence-transformers>=2.2.0
scikit-learn>=1.3.0
numpy>=1.24.0
```
---
## 🧠 Running the Server
> **Note**: The first time you run the server, it will download the `all-MiniLM-L6-v2` model from sentence-transformers. This may take a few seconds depending on your internet connection.
### Start with Dual Transport (stdio + HTTP)
```bash
python server.py --transport stdio,http --port 8003
```
This enables both MCP stdio communication and HTTP REST API access.
### HTTP-only Mode
```bash
python server.py --transport http --port 8003
```
### Stdio-only Mode (for MCP clients)
```bash
python server.py --transport stdio
```
### Using Uvicorn Directly
```bash
uvicorn server:app --host 0.0.0.0 --port 8003
```
### Configuration Options
- `--transport`: Transport mode (stdio, http, or stdio,http) - default: stdio
- `--port`: HTTP port number - default: 8000
- `--host`: Host to bind to - default: 0.0.0.0
- `--storage_path`: Path to store tool embeddings - default: tool_embeddings.json
By default, the server starts at:
👉 `http://localhost:8003` (when HTTP transport is enabled)
The server automatically:
- Creates a `logs/` directory for application logs
- Loads existing tools from `tool_embeddings.json` on startup
- Saves tools to disk after any modification
---
## 🧪 Testing the API
The server provides two interfaces:
1. **REST API**: Available at `/api/*` endpoints (see [CURLS.md](./CURLS.md) for examples)
2. **MCP Tools**: Available via MCP protocol (see [MCP_TOOLS.md](./MCP_TOOLS.md) for documentation)
### REST API Endpoints
All endpoints return structured JSON responses with appropriate status codes.
#### Check Server Status
```bash
curl http://localhost:8003/api/status
```
#### Upload Tools via JSON
```bash
curl -X POST http://localhost:8003/api/tools/upload-json \
-H "Content-Type: application/json" \
-d '{"tools": [{"type": "function", "name": "get_weather", "description": "Get the current weather for a specific city.", "parameters": {"type": "object", "properties": {"city": {"type": "string", "description": "The name of the city to get weather for."}}}}]}'
```
#### Upload Tools via File
```bash
curl -X POST http://localhost:8003/api/tools/upload-file \
-F "file=@test_tools.json;type=application/json"
```
#### Search for Similar Tools
```bash
curl -X POST http://localhost:8003/api/tools/search \
-H "Content-Type: application/json" \
-d '{"query": "weather forecast for a city", "k": 3}'
```
#### Get Statistics
```bash
curl http://localhost:8003/api/tools/stats
```
#### Delete Specific Tools
```bash
curl -X DELETE http://localhost:8003/api/tools/delete \
-H "Content-Type: application/json" \
-d '{"tool_names": ["get_weather", "get_news_headlines"]}'
```
#### Clear All Tools
```bash
curl -X DELETE http://localhost:8003/api/tools/clear
```
### MCP Access
The MCP endpoint is mounted at `/mcp` for HTTP streaming mode:
```bash
curl http://localhost:8003/mcp
```
For full MCP tool documentation, see [MCP_TOOLS.md](./MCP_TOOLS.md).
For more comprehensive testing examples, see [CURLS.md](./CURLS.md).
---
## 🧰 Example MCP Configuration
To integrate with an MCP client (like Claude Desktop):
```json
{
"mcpServers": {
"one-mcp-server": {
"command": "python",
"args": [
"/absolute/path/to/server.py",
"--transport", "stdio",
"--storage_path", "tool_embeddings.json"
]
}
}
}
```
For dual transport mode (stdio for MCP + HTTP for REST API):
```json
{
"mcpServers": {
"one-mcp-server": {
"command": "python",
"args": [
"/absolute/path/to/server.py",
"--transport", "stdio,http",
"--port", "8004",
"--storage_path", "tool_embeddings.json"
]
}
}
}
```
---
## 🏗️ Architecture
### Components
- **server.py**: Entry point that initializes the app and starts the MCP server
- **mcp_server.py**: Handles multi-transport server orchestration (stdio/HTTP/dual)
- **api.py**: FastAPI application factory and REST endpoint definitions
- **mcp_tools.py**: MCP tool decorators and function implementations
- **tools_store.py**: Singleton store for tool embeddings with search capability
- **models.py**: Pydantic models for type safety and validation
- **config.py**: Configuration management and CLI argument parsing
- **logging_setup.py**: Centralized logging with rotating file handlers
### How It Works
1. **Tool Storage**: Tools are stored with their embeddings using `sentence-transformers`
2. **Semantic Search**: Query embeddings are compared using cosine similarity
3. **Persistence**: Tools automatically saved to `tool_embeddings.json`
4. **Dual Interface**: Same functionality available via REST API and MCP tools
5. **Multi-Transport**: Server can run stdio (for MCP clients) and HTTP simultaneously
---
### Dev
1. Create zip: `zip -r one-mcp.zip . -x "*.git/*" -x ".env" -x ".DS_Store" -x ".dockerignore" -x ".gitignore"`
---
## 🧑💻 Contributing
Contributions are welcome!
To contribute:
1. **Fork** the repository
2. **Create** a new feature branch (`git checkout -b feature/my-feature`)
3. **Commit** your changes (`git commit -m "Add my feature"`)
4. **Push** to your fork (`git push origin feature/my-feature`)
5. **Submit a Pull Request**
Before submitting, ensure:
* Code passes linting and basic tests.
* You’ve updated documentation if needed.
---
## 📜 License
This project is licensed under the **MIT License** — see the [LICENSE](LICENSE) file for details.
---
## 💬 Support
If you encounter any issues or have feature requests:
* Open an issue on [GitHub](https://github.com/freakynit/one-mcp/issues)
* Or contact [@freakynit](https://github.com/freakynit) directly.
