furoku_mcp

Personal experimental MCP server with extensible tool collection.

Features

• ping / http_ping tools
• Unified JSON result format (success / error) for tool responses
• Config + environment variable overrides with validation
• Structured logging (levels + optional timing helper)
• TypeScript + MCP SDK scaffold (incrementally extensible)

Quick Start

Install Dependencies

npm install

Build

npm run build

Test Locally

node build/index.js

(Server will start and wait for MCP client connections via stdio)

Add to Claude Code

claude mcp add furoku_mcp -s user -- npx furoku-mcp@latest

(Alternative) Claude Desktop Configuration

Claude Desktop を使う場合は設定ファイルに本サーバーを追加できます。以下の例ファイルを claude-desktop.mcp.example.json として同梱しています。

1. ファイルをコピー:

cp claude-desktop.mcp.example.json ~/Library/Application\ Support/Claude/claude_desktop_config.json

既存設定がある場合は "mcpServers" オブジェクト内にマージしてください。 2. Claude Desktop を再起動 3. ツール一覧に furoku_mcp が表示されれば成功

ローカル開発版を使いたい場合は args をビルド成果物に変更します:

{
  "mcpServers": {
    "furoku_mcp": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/repo/build/index.js"]
    }
  }
}

※ macOS でパスにスペースが含まれる場合は CLI で引用符で囲んでください。

Remove from Claude Code

claude mcp remove furoku_mcp

Available Tools

ping

Echo tool. Returns structured JSON (stringified text block) with metadata.

Input:

• message (string, required)

Response (stringified JSON example):

{
  "success": true,
  "data": {
    "echo": "Hello furoku_mcp!",
    "timestamp": "2025-08-22T10:30:45.123Z",
    "server": "furoku_mcp"
  }
}

http_ping

Lightweight reachability / latency check.

Input:

• url (string, required) http/https
• method (string, optional) HEAD (default) | GET
• timeoutMs (number, optional) overrides default timeout

Response (success example, JSON stringified):

{
  "success": true,
  "data": {
    "url": "https://www.yahoo.co.jp",
    "method": "HEAD",
    "status": 200,
    "ok": true,
    "redirected": false,
    "finalUrl": "https://www.yahoo.co.jp/",
    "durationMs": 114,
    "headers": {
      "content-type": "text/html; charset=utf-8",
      "server": "nginx"
    }
  }
}

Error example (timeout):

{
  "success": false,
  "error": {
    "message": "timeout",
    "code": "AbortError",
    "details": { "url": "https://example.com", "method": "HEAD", "durationMs": 5001 }
  }
}

Development

Watch Mode

npm run dev

Type Checking

npm run lint

Adding New Tools

1. Add tool definition to the tools array in src/index.ts
2. Add corresponding handler in the CallTool request handler
3. Update this README with tool documentation
4. Rebuild and test

Publishing

# Update version in package.json
npm run build
npm publish --access public

CHANGELOG & Tagging (Recommended)

# After updating CHANGELOG.md
git add CHANGELOG.md README.md src
git commit -m "chore: release 0.1.1"
git tag v0.1.1
git push origin main --tags

Configuration

You can control behavior via environment variables or an optional furoku_mcp.config.json (working directory by default):

Env vars:

• FUROKU_MCP_LOG_LEVEL debug | info | warn | error (default: info)
• FUROKU_MCP_LOG_FORMAT set to plain to disable JSON structured logs
• FUROKU_MCP_TIMEOUT_MS default timeout for tools like http_ping
• FUROKU_MCP_ALLOWED_HOSTS comma separated allow-list (exact domain or suffix). Empty => no restriction
• FUROKU_MCP_CONFIG path to explicit config file

Example config file:

{
  "logLevel": "debug",
  "defaultTimeoutMs": 7000,
  "allowedHosts": ["example.com", "api.example.com"]
}

License

MIT License. See LICENSE file for details.

References

• Model Context Protocol
• MCP SDK Documentation