# local-mcp

An extensible local Model Context Protocol (MCP) server for building and running tools from VS Code. Weather is the first tool set in the repository, and additional tools can be added over time.

The server communicates over stdio. The current implementation exposes two weather tools backed by the US National Weather Service API:

- `get_alerts`: returns active weather alerts for a two-letter US state code, such as `CA` or `NY`.
- `get_forecast`: returns the forecast for a latitude and longitude. The National Weather Service API supports US locations only.

## Requirements

- Node.js 20 or later
- npm
- VS Code with MCP support

## Set up locally

Clone the repository and install its dependencies:

```bash
git clone <repository-url>
cd local-mcp
npm install
```

Build the TypeScript source:

```bash
npm run build
```

The compiled server is written to `build/index.js`. To run it directly:

```bash
node build/index.js
```

The server uses stdio, so it is intended to be started by an MCP client rather than used as an interactive terminal command. It logs status and errors to stderr while MCP messages use stdin/stdout.

## Use with VS Code

After building the project, add an MCP configuration file at `.vscode/mcp.json` in this repository, or add the same server to your user-level MCP configuration. The configuration starts the whole local MCP server, so tools registered in the server become available through the same entry point:

```json
{
	"servers": {
		"local-mcp": {
			"type": "stdio",
			"command": "node",
			"args": ["${workspaceFolder}/build/index.js"]
		}
	}
}
```

Start or restart the `local-mcp` server from VS Code. The registered tools will then be available to supported chat experiences in the workspace.

If the project is stored outside the active workspace, replace `${workspaceFolder}/build/index.js` with the absolute path to the compiled `build/index.js` file.

## Current tools: weather

### `get_alerts`

```json
{
	"state": "CA"
}
```

`state` must be exactly two characters. The server normalizes the value to uppercase before requesting alerts.

### `get_forecast`

```json
{
	"latitude": 37.7749,
	"longitude": -122.4194
}
```

`latitude` must be between `-90` and `90`, and `longitude` must be between `-180` and `180`.

## Adding more tools

Add each tool’s implementation to its own module under `src/`, then register it in `src/index.ts`. Rebuild the project after making changes:

```bash
npm run build
```

Update the current tools section above when adding or changing tool inputs. The VS Code MCP configuration does not need to change unless the server entry point or launch command changes.

## Development

After changing files in `src/`, rebuild the server:

```bash
npm run build
```

The upstream weather data comes from [api.weather.gov](https://api.weather.gov/). Network access is required when a tool is called. The project does not currently include automated tests; `npm test` is the placeholder npm script.

## Project structure

```text
src/
	index.ts    MCP server setup and tool registration
	weather.ts  Current weather tool implementations
build/        Compiled JavaScript output
```