McpToolbox.Tools.Basic 0.0.0-test-20251230232759

McpToolbox

A suite of MCP (Model Context Protocol) server tools built with .NET 10. McpToolbox provides reusable tool libraries and a host application that exposes them via MCP stdio transport and an HTTP proxy.

Architecture

This repository is organized as a multi-project solution:

• McpToolbox (ToolHost) — The main MCP server application (packaged as a dotnet global tool)
• McpToolbox.Tools.Basic — Fundamental operations (echo, math, datetime)
• McpToolbox.Tools.Data — JSON, CSV, XML, Base64, hashing
• McpToolbox.Tools.Text — Regex, text search, encoding, templates
• McpToolbox.Tools.Reflection — .NET assembly inspection and analysis
• McpToolbox.Tools.Web — HTTP operations, file downloads, URL handling
• McpToolbox.Tools.Knowledge — Persistent fact storage with JSON export/import

All tool libraries are published as separate NuGet packages for reuse in other MCP servers.

Tools

Basic Tools

• Echo: Echoes a message back to the client.
• Add: Adds two numbers.
• Multiply: Multiplies two numbers.
• GetCurrentDateTime: Gets the current date and time.

Reflection Tools

• LoadAssembly: Loads an assembly from a file path and returns basic information.
• GetAssemblyTypes: Gets all types in a specified assembly.
• GetExportedTypes: Gets all exported (public) types in the assembly.
• GetTypeInfo: Gets information about a specific type in an assembly.
• GetTypeMethods: Gets all methods of a specific type in an assembly.
• GetTypeProperties: Gets all properties of a specific type in an assembly.

Text Tools

• RegexMatch: Matches text against a regular expression pattern.
• RegexReplace: Replaces text matching a regular expression pattern.
• SearchInFile: Searches for a text pattern in a file and returns matching lines.
• FormatTemplate: Formats text using a template with placeholders.
• ConvertEncoding: Converts text between different encodings.

Data Tools

• ParseJson: Parses JSON and returns formatted or queried result.
• ToJson: Converts data to JSON format.
• ParseCsv: Parses CSV data and returns formatted output.
• Base64Encode: Encodes text to Base64.
• Base64Decode: Decodes Base64 text.
• ComputeHash: Computes a hash of text using MD5, SHA1, SHA256, SHA384, or SHA512.
• ParseXml: Validates and parses XML data.

Web Tools

• HttpGet: Performs an HTTP GET request.
• HttpPost: Performs an HTTP POST request.
• HttpPut: Performs an HTTP PUT request.
• HttpDelete: Performs an HTTP DELETE request.
• DownloadFile: Downloads a file from a URL.
• ParseUrl: Parses and validates a URL, returning its components.
• UrlEncode: URL encodes a string.
• UrlDecode: URL decodes a string.

Knowledge Tools

• AddFact: Adds a fact to the persistent knowledge database.
• SearchFacts: Searches for facts containing a keyword (supports regex).
• RemoveFact: Removes a fact by ID.
• ClearFacts: Clears all facts from the database.
• GetFactCount: Gets the total number of stored facts.
• ExportFacts: Returns all facts as JSON.
• ImportFacts: Imports facts from a JSON array.
• ExampleFacts: Returns example facts to help format input.

Installation

As a dotnet global tool

As a dotnet global tool

Install from NuGet.org:

dotnet tool install -g McpToolbox
# or to update
dotnet tool update -g McpToolbox

Then run:

mcp-toolbox

Local development

Build and run the ToolHost directly:

dotnet build -c Release McpToolbox.sln
dotnet run --project src/McpToolbox.ToolHost/McpToolbox.ToolHost.csproj

Local deployment (Windows PowerShell)

Use the publish script to create a self-contained executable:

.\publish.ps1

This publishes to C:\MCP\McpToolbox\ by default. Customize the path:

.\publish.ps1 -DeployPath "C:\MyDeployment\McpToolbox"

Docker

Build and run via Docker:

docker build -t mcptoolbox .
docker run -d -p 8080:8080 --name mcptoolbox mcptoolbox

The container runs the HTTP proxy only (stdio transport is disabled via MCP_STDIO=0).

Pre-built images are available at ghcr.io/merp4/mcptoolbox:latest.

HTTP Proxy

The ToolHost exposes an HTTP proxy for MCP tool invocation:

• POST /mcp/invoke — Invoke a tool method
  • Body: {"Tool": "BasicTools", "Method": "Add", "Args": [2, 3]}
  • Returns: {"result": 5}
• GET /mcp/tools — List available tool classes

Optional API key authentication via MCP_HTTP_API_KEY environment variable and X-API-Key header.

Tests

Integration tests are in tests/integration.sh. They exercise core tool flows via the HTTP proxy.

Run against a local container:

docker run -d --name mcptest -p 8080:8080 mcptoolbox
chmod +x tests/integration.sh
./tests/integration.sh http://localhost:8080
docker rm -f mcptest

CI/CD

Workflows in .github/workflows/:

• ci-integration.yml — Builds Docker image and runs integration tests on PRs
• ghcr-publish.yml — Publishes Docker images to GHCR on tag pushes
• dotnet-tool-publish.yml — Packs and publishes all NuGet packages on tag pushes
• release.yml — Creates GitHub releases with .nupkg artifacts

Secrets

• NUGET_API_KEY — NuGet.org API key (required for package publishing)
• GITHUB_TOKEN — Auto-provided for releases and GHCR

Versioning

Package versions are derived from git tags in CI. To release:

git tag -a v1.0.0 -m "Release v1.0.0"
git push origin v1.0.0

CI will pack all libraries and the ToolHost with version 1.0.0 and publish to NuGet/GHCR.

Contributing

See CONTRIBUTING.md for developer setup, release process, and guidelines.

VS Code MCP Integration

Configure .vscode/mcp.json to use the local installation:

{
  "servers": {
    "mcp-toolbox": {
      "type": "stdio",
      "command": "C:\\MCP\\McpToolbox\\McpToolbox.exe"
    }
  }
}

Or use the dotnet tool:

{
  "servers": {
    "mcp-toolbox": {
      "type": "stdio",
      "command": "mcp-toolbox"
    }
  }
}

License

MIT License - see LICENSE.

## HTTP MCP API (Docker / container)

The app exposes a simple HTTP proxy for MCP tools at `/mcp`. By default the container listens on port `8080`.

- Start container (bind port 8080):

```bash
docker run -p 8080:8080 ghcr.io/<owner>/<repo>:latest

• If you set an API key, export it into the container as MCP_HTTP_API_KEY and requests to /mcp/* must include header X-API-Key: <key>.

• Invoke a tool method (JSON POST to /mcp/invoke):

curl -X POST http://localhost:8080/mcp/invoke \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <your-key>" \
  -d '{"Tool":"KnowledgeTools","Method":"AddFact","Args":["The sky is blue."]}'

• List available tool classes:

curl http://localhost:8080/mcp/tools