my-bike-spots

A Model Context Protocol (MCP) server for finding safe bike parking and checking theft statistics. Built with mcp-framework.

Quick Start

# Install dependencies
npm install

# Build the project
npm run build

Project Structure

myBikeSpots/
├── src/
│   ├── tools/                    # MCP Tools
│   │   ├── FindBikeParking.ts    # Find bike parking near an address
│   │   └── GetBikeInfo.ts        # Search stolen bikes and theft data
│   ├── resources/                # MCP Resources
│   │   ├── MapGuidelines.ts      # OpenStreetMap usage guidelines
│   │   ├── BikeIndexAPI.ts       # BikeIndex API documentation
│   │   ├── OpenStreetMap.ts      # OSM API documentation
│   │   └── BIAPIDocs.ts          # GetBikeInfo tool usage guidelines
│   ├── prompts/                  # MCP Prompts
│   │   └── MyPrompt.ts           # Greeting and context prompts
│   ├── Bike.interface.ts         # Bike data interface
│   ├── BikePark.interface.ts     # Bike parking input interface
│   └── index.ts                  # Server entry point
├── package.json
└── tsconfig.json

Adding Components

This project includes two main tools:

• FindBikeParking.ts - Finds bike parking spots using OpenStreetMap data
• GetBikeInfo.ts - Searches for stolen bikes via BikeIndex API

You can add more tools using the CLI:

# Add a new tool
mcp add tool my-tool

# Example tools you might add:
mcp add tool bike-route-planner
mcp add tool bike-shop-finder
mcp add tool repair-tracker

Tool Development

Tool 1: FindBikeParking

import { MCPTool } from "mcp-framework";
import { z } from "zod";

class FindBikeParking extends MCPTool<BikeParkInput> {
  name = "find-bike-parking";
  description = "Find Bike Parking provided an address/coordinates by the user";

  schema = {
    location: {
      type: z.string(),
      description: "Location of choice you want to park your bike at",
    },
    coordinates: {
      type: z.array(z.number()).length(4).optional(),
      description: "GPS Bounding Box [left, bottom, right, top]",
    },
  };

  async execute({ location, coordinates }: BikeParkInput) {
    // Geocode address → Query OpenStreetMap → Fetch theft data
    // Returns parking spots with Google Maps links and safety info
  }
}

Usage example:

"Find bike parking near 123 Main Street, Portland, OR"
"Show me bike racks in downtown Seattle"

Tool 2: GetBikeInfo

import { MCPTool } from "mcp-framework";
import { z } from "zod";

class GetBikeInfo extends MCPTool<BikeInput> {
  name = "get-bike-info";
  description = "Search for stolen bikes and theft reports from BikeIndex";

  schema = {
    query: {
      type: z.string(),
      description: "Search term (required): bike model, color, serial number",
    },
    stolenness: {
      type: z.enum(["stolen", "proximity", "non", "all"]).optional(),
      description: "Filter by theft status",
    },
    location: {
      type: z.string().optional(),
      description: "Location to search near",
    },
    distance: {
      type: z.string().optional(),
      description: "Search radius in miles (default: 10)",
    },
  };

  async execute(input: BikeInput) {
    // Query BikeIndex API for stolen bike reports
    // Returns theft data with details and locations
  }
}

Usage example:

"Search for stolen Trek bikes in Brooklyn"
"Show me bike thefts near the Mission District, San Francisco"
"Find reports of a blue Specialized bike"

Publishing to npm

1. Update your package.json:

   • Ensure name is unique and follows npm naming conventions
   • Set appropriate version
   • Add description, author, license, etc.
   • Check bin points to the correct entry file

2. Build and test locally:

   npm run build
   npm link
   my-bike-spots  # Test your CLI locally

3. Login to npm (create account if necessary):

   npm login

4. Publish your package:

   npm publish

After publishing, users can add it to their Claude Desktop client (read below) or run it with:

npx my-bike-spots

Using with Claude Desktop

Local Development

Add this configuration to your Claude Desktop config file:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "my-bike-spots": {
      "command": "node",
      "args":["/absolute/path/to/myBikeSpots/dist/index.js"]
    }
  }
}

After Publishing

Add this configuration to your Claude Desktop config file:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "my-bike-spots": {
      "command": "npx",
      "args": ["-y", "my-bike-spots"]
    }
  }
}

Building and Testing

1. Make changes to your tools
2. Run npm run build to compile
3. The server will automatically load your tools on startup

Learn More

• MCP Framework Github
• MCP Framework Docs