# mcp-tools-server

Small remote MCP server for course experiments with Model Context Protocol

The project exposes custom MCP tools over Streamable HTTP

## Current tools

### get_recent_commits

Returns recent commits from a public GitHub repository

Input parameters:

* `owner` — GitHub repository owner, for example `JetBrains`
* `repo` — GitHub repository name, for example `kotlin`
* `limit` — number of commits to return, from `1` to `10`

Example input:

```json
{
  "owner": "JetBrains",
  "repo": "kotlin",
  "limit": 3
}
```

The tool calls the public GitHub REST API and returns a short text summary with commit SHA, message, author, date and URL

### start_price_watch

Starts periodic price monitoring for a market symbol and stores snapshots in JSON

Input parameters:

* `symbol` — market symbol, for example `BTCUSDT`
* `intervalSeconds` — collection interval in seconds, from `10` to `3600`

### get_price_watch_summary

Returns an aggregated summary for collected price snapshots

Summary includes:

* snapshots count
* first and last price
* min and max price
* average price
* absolute and percentage change
* recent snapshots

### stop_price_watch

Stops periodic price monitoring for a market symbol and removes stored watch state

### search_recent_commits

Searches recent commits for a public GitHub repository

This tool is used as the first step of the MCP tool composition pipeline

Input parameters:

* `owner` — GitHub repository owner, for example `JetBrains`
* `repo` — GitHub repository name, for example `kotlin`
* `limit` — number of commits to fetch, from `1` to `20`

### summarize_text

Creates a short deterministic summary for provided text

This tool is used as the second step of the MCP tool composition pipeline

Input parameters:

* `title` — summary title
* `sourceText` — source text to summarize

### save_note_to_file

Saves provided note content to a Markdown file

This tool is used as the third step of the MCP tool composition pipeline

Input parameters:

* `title` — note title used for file name
* `content` — Markdown content to save

Saved notes are created in:

```text
storage/notes/
```

### echo

Simple test tool that returns the input text back to the client

Used to verify that MCP tool calls work

## Storage

Price watch data is stored locally in:

```text
storage/price-watch-state.json
```

Pipeline notes are stored locally in:

```text
storage/notes/
```

Runtime storage files are created automatically and are not committed to Git

## Endpoints

### GET /

Health-check endpoint

Example response:

```json
{
  "service": "mcp-tools-server",
  "status": "ok",
  "tools": [
    "echo",
    "get_recent_commits",
    "start_price_watch",
    "get_price_watch_summary",
    "stop_price_watch",
    "search_recent_commits",
    "summarize_text",
    "save_note_to_file"
  ]
}
```

### POST /mcp

MCP endpoint for Streamable HTTP clients

## Run locally

Install dependencies:

```bash
npm install
```

Start development server:

```bash
npm run dev
```

Build project:

```bash
npm run build
```

Start compiled version:

```bash
npm start
```

By default the server runs on port `3000`.

Local MCP endpoint:

```text
http://localhost:3000/mcp
```

## Test with MCP Inspector

Start the server:

```bash
npm run dev
```

Run MCP Inspector:

```bash
npx @modelcontextprotocol/inspector
```

Use the following settings:

```text
Transport Type: Streamable HTTP
URL: http://localhost:3000/mcp
```

Then open the Tools tab, list available tools and run the required tool

## Notes

Current limitations:

* only public GitHub repositories are supported;
* GitHub requests are unauthenticated;
* unauthenticated GitHub API rate limits apply;
* the price watcher uses an in-process `setInterval` scheduler and JSON file storage;
* locally, scheduled jobs work while the Node.js process is running;
* `summarize_text` uses deterministic text processing, not an LLM.