Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 0 additions & 40 deletions .github/workflows/release.yml

This file was deleted.

95 changes: 0 additions & 95 deletions .goreleaser.yml

This file was deleted.

44 changes: 6 additions & 38 deletions Makefile
Original file line number Diff line number Diff line change
@@ -1,15 +1,13 @@
# Makefile for note-mcp project

.PHONY: all clean build test notecard notehub blues-expert inspect inspect-notecard inspect-notehub inspect-blues-expert help docs docs-notehub docs-notecard docs-blues-expert fmt vet develop
.PHONY: all clean build test blues-expert inspect-blues-expert help docs docs-blues-expert fmt vet develop

# Go build flags
GO=go
GOFLAGS=-v
LDFLAGS=-w -s

# Project directories
NOTECARD_DIR=./notecard
NOTEHUB_DIR=./notehub
BLUES_EXPERT_DIR=./blues-expert

# Default target
Expand All @@ -21,30 +19,14 @@ help: ## Show this help message
@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf " \033[36m%-20s\033[0m %s\n", $$1, $$2}'

# Build targets
build: notecard notehub blues-expert ## Build all MCP servers
build: blues-expert ## Build all MCP servers
@echo "✓ Build complete"

# Build targets for each MCP server
notecard: ## Build the Notecard MCP server
@echo "Building notecard..."
cd $(NOTECARD_DIR) && $(GO) build $(GOFLAGS) -ldflags "$(LDFLAGS)" -o notecard

notehub: ## Build the Notehub MCP server
@echo "Building notehub..."
cd $(NOTEHUB_DIR) && $(GO) build $(GOFLAGS) -ldflags "$(LDFLAGS)" -o notehub

blues-expert: ## Build the Blues Expert MCP server
@echo "Building blues-expert..."
cd $(BLUES_EXPERT_DIR) && $(GO) build $(GOFLAGS) -ldflags "$(LDFLAGS)" -o blues-expert

inspect-notecard: notecard ## Run MCP inspector for notecard
@echo "Starting MCP inspector for notecard..."
npx @modelcontextprotocol/inspector --config mcp.json --server notecard

inspect-notehub: notehub ## Run MCP inspector for notehub
@echo "Starting MCP inspector for notehub..."
npx @modelcontextprotocol/inspector --config mcp.json --server notehub

inspect-blues-expert: blues-expert ## Run MCP inspector for blues-expert
@echo "Starting MCP inspector for blues-expert..."
npx @modelcontextprotocol/inspector --config mcp.json --server blues-expert
Expand All @@ -54,19 +36,7 @@ inspect-blues-expert: blues-expert ## Run MCP inspector for blues-expert
@:

# Documentation targets
docs: docs-notehub docs-notecard docs-blues-expert ## Generate documentation for all packages

docs-notehub: ## Generate Go documentation for notehub package
@echo "Generating Notehub API documentation..."
@mkdir -p notehub/docs
@go doc -all ./notehub > ./notehub/docs/API_DOCS.md
@echo "✓ Notehub documentation generated: notehub/docs/API_DOCS.md"

docs-notecard: ## Generate Go documentation for notecard package
@echo "Generating Notecard API documentation..."
@mkdir -p notecard/docs
@go doc -all ./notecard > ./notecard/docs/API_DOCS.md
@echo "✓ Notecard documentation generated: notecard/docs/API_DOCS.md"
docs: docs-blues-expert ## Generate documentation for all packages

docs-blues-expert: ## Generate Go documentation for blues-expert package
@echo "Generating Blues Expert API documentation..."
Expand All @@ -81,20 +51,18 @@ test: ## Run tests for all packages

clean: ## Clean build artifacts and generated docs
@echo "Cleaning build artifacts..."
rm -f $(NOTECARD_DIR)/notecard
rm -f $(NOTEHUB_DIR)/notehub
rm -f $(BLUES_EXPERT_DIR)/blues-expert
@rm -rf notehub/docs notecard/docs blues-expert/docs
@rm -rf blues-expert/docs
@echo "✓ Clean complete"

# Utility targets
fmt: ## Format Go code
@echo "Formatting Go code..."
@go fmt ./notehub/... ./notecard/... ./blues-expert/...
@go fmt ./blues-expert/...
@echo "✓ Code formatted"

vet: ## Run go vet on all packages
@go vet ./notehub/... ./notecard/... ./blues-expert/...
@go vet ./blues-expert/...
@echo "✓ Vet complete"

develop: fmt vet test docs build ## Run full development workflow (format, vet, test, docs, build)
87 changes: 12 additions & 75 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,110 +1,47 @@
# note-mcp

MCP servers for Notecard, Notehub, and Blues Expert.
Blues Expert MCP server for Notecard & Notehub development.

> [!WARNING]
> These MCP servers are experimental and subject to change. Please wait until a versioned release is available before relying on them.
> This MCP server is experimental and subject to change. Please wait until a versioned release is available before relying on it.

## About

This project is a collection of MCP servers for Notecard, Notehub, and Blues Expert.

### Notecard (STDIO)

The Notecard MCP server is a local tool design to help you develop Notecard projects.
It provides a simple abstraction to Notecard (using the Notecard CLI), and can help you get started setting up and configuring your Notecards.
This tool provides utilities to update firmware, connect your Notecards to WiFi networks, and more.

#### Prerequisites

- [Notecard CLI](https://github.com/blues/notecard-cli)

### Notehub (STDIO)

The Notehub MCP server is a local tool design to help you develop Notehub projects.
It provides a simple abstraction to Notehub (using the Notehub API), and can help you get started setting up and configuring your Notehub projects.
This tool provides utilities to create and manage Notehub projects, view Note events,and to manage your Notehub devices.

### Blues Expert (Docker/HTTP)

The Blues Expert MCP server is a remote tool design to help you develop Notecard projects.
When used with an LLM, it can help to guide with best practices, for both writing code as well as leveraging Notecard's capabilities.
The Blues Expert MCP provides correct and accurate information about Notecard, and can help to reduce hallucinations and errors generated by LLMs when building Notecard projects.
Use this tool to accelerate your development process, and to ensure that your projects are built correctly and efficiently according to best practices.
The Blues Expert MCP server is a remote tool designed to help you develop Notecard projects.
When used with an LLM, it provides guidance on best practices for writing firmware and leveraging Notecard's capabilities.
It provides correct and accurate information about Notecard, reducing hallucinations and errors when building Notecard projects.

## Build

To build the MCP servers, you'll need to have the following tools installed:
Requirements:

- Go (atleast v1.23)
- Go (at least v1.23)
- Make

Per MCP server, you'll need to have the following tools installed:

- Notecard MCP: [Notecard CLI](https://github.com/blues/notecard-cli)
- Notehub MCP: Notehub Account with API access
- Blues Expert MCP: [Docker](https://www.docker.com/products/docker-desktop/)

Then, run the following command:
- [Docker](https://www.docker.com/products/docker-desktop/)

```bash
make build
```

## Install

Add the following to your `mcp.json` file, where `mcp.json` is the file that determines where the MCP servers are located (e.g. for Claude Desktop, this is `claude_desktop_config.json`):
Add the following to your `mcp.json` file (e.g. for Claude Desktop, this is `claude_desktop_config.json`):

```json
{
"mcpServers": {
"notecard": {
"type": "stdio",
"command": "/YOUR/PATH/TO/note-mcp/notecard/notecard"
},
"notehub": {
"type": "stdio",
"command": "/YOUR/PATH/TO/note-mcp/notehub/notehub",
"args": [
"--env",
"/YOUR/PATH/TO/note-mcp/.env"
]
},
"blues-expert": {
"type": "http",
"url": "http://localhost:8080/expert/mcp"
}
},
}
}
```

The `.env` file for Notehub MCP should contain the following variables:

```bash
NOTEHUB_USER="your_notehub_username"
NOTEHUB_PASS="your_notehub_password"
```

Additional variables will be added.

## Development

To run the MCP inspector, you'll need nodejs installed (atleast v18).

For Notecard MCP:

```bash
make inspect notecard
```

For Notehub MCP:

```bash
make inspect notehub
```

For Blues Expert MCP:
To run the MCP inspector, you'll need Node.js installed (at least v18).

```bash
make inspect blues-expert
make inspect-blues-expert
```
3 changes: 1 addition & 2 deletions blues-expert/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,6 @@ import (
"os"

"note-mcp/blues-expert/lib"
"note-mcp/utils"

"github.com/joho/godotenv"
"github.com/modelcontextprotocol/go-sdk/mcp"
Expand Down Expand Up @@ -71,7 +70,7 @@ func main() {
sessionManager = lib.NewSessionManager()

// Create a new MCP server
impl := &mcp.Implementation{Name: "Blues Expert MCP", Version: utils.Commit}
impl := &mcp.Implementation{Name: "Blues Expert MCP", Version: commit}
opts := &mcp.ServerOptions{
Instructions: "This MCP server provides expert guidance on using the Blues Notecard & Notehub. When using this tool for developing firmware, use the 'firmware_entrypoint' tool to get started. Otherwise, use the 'docs_search' or 'docs_search_expert' tool to search the Blues documentation.",
HasTools: true,
Expand Down
4 changes: 2 additions & 2 deletions utils/version.go → blues-expert/version.go
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
package utils
package main

import "runtime/debug"

var Commit = func() string {
var commit = func() string {
if info, ok := debug.ReadBuildInfo(); ok {
for _, setting := range info.Settings {
if setting.Key == "vcs.revision" {
Expand Down
Loading
Loading