PROJECT IN EXTREME POC MODE - NOTHING STABLE AT ALL - DOCS AND VISION ARE PURELY NOTES

BLAH - Barely Logical Agent Host - Update #1

(think npmjs for tools)

Once this list is fully done, the BLAH JSON schema will be finalized.

Notes:

The flows will be using a subset of agnt.gg's flow schema
Extend means you can compose blah.json's in any way you like. (think what if you just want to include a designers you follow tools)
The registry means we will have a convenient way to just push and pull functions (tools)

BLAH - Barely Logical Agent Host

BLAH is an open-source ecosystem for managing, distributing, and executing AI agent tools using the Model Context Protocol (MCP). It provides a decentralized registry for MCP servers that promotes transparency, security, and community-driven development.

Project Structure

This project is organized as a monorepo using Turborepo:

packages/cli - The main BLAH CLI tool for working with MCP
apps/web - Web interface for BLAH
apps/docs - Documentation site

Getting Started

Prerequisites

Node.js >= 18.18.0 (Node 20+ recommended)
pnpm

Installation

# Clone the repository
git clone https://github.com/thomasdavis/blah.git
cd blah

# Install dependencies
pnpm install

# Build the project
pnpm run build

Quick Start with the CLI

See the CLI README for detailed instructions on using the BLAH CLI.

# Navigate to the CLI package
cd packages/cli

# Set up your environment variables (.env file)
echo "OPENAI_API_KEY=your_openai_api_key_here" > .env
echo "BLAH_HOST=https://ajax-blah.web.val.run" >> .env

# Run a simulation
pnpm run simulate

Currently working on

Need a way to debug mcp servers using any model/ide
Think about portals
lisa watts came up with "auton", likely what i am going to suggest

Unrelated Ideas

Need save state in ideas so you don't lose stuff (if you hadn't comitted)
upvotes for social tooling
automatic error rate
share your tool combination results

Using a local blah.json

Hosted blah.json (Valtown)

Getting started (hosted)

Setup a Valtown account
Create a new HTTP function named blah

export default async function server(request: Request): Promise<Response> {
  const tools = [
    {
      name: "hello_name",
      description: `Says hello to the name`,
      inputSchema: {
        type: "object",
        properties: {
          name: {
            type: "string",
            description: `Name to say hello to`,
          },
        },
      },
    },
  ];

  return new Response(JSON.stringify(tools), {
    headers: {
      "Content-Type": "application/json",
    },
    status: 200,
  });
}

Adding to your Client

Claude
- Desktop
- Code (CLI)
Cursor
Cline
Windsurf
BLAH Client
Are there any nice web clients yet

Development

I am still working on tools to make development not shit.

Logging

While developing this, I want to send logs from everybodies clients to just figure out all the fucking errors the clients are throwing due to different configures.

Playground

So far just a basic client that lists prompts, resources, and tools. Could be interactive later, and should also run against tests.

npm run playground

Needs improvement

Valtown is the current wrapper, need to be an alternative maybe using Vercel functions or some shit.
Need a nice strategy for composability

Credits

Lisa Watts
Travis
Wombat

AI GENERATED BULL SHIT (the above is authentic)

mcp server version badge
registry uptime status

What is BLAH?

BLAH is an open-source ecosystem for managing, distributing, and executing AI agent tools using the Model Context Protocol (MCP). It provides a decentralized registry for MCP servers that doesn't suffer from misaligned incentives, promoting transparency, security, and community-driven development.

Key Features:

Open-source infrastructure that any system (IDE, AI platform, etc.) can connect to
Language-agnostic tool registry supporting unlimited tool selection
Robust security through optional signing and verification of MCP servers
Comprehensive CLI for publishing, discovering, and managing tools
Support for various tool types: functions, REST endpoints, local files, or standard manifests

🔍 Vision

BLAH aims to be the foundation for a new generation of AI tools that can be easily shared, discovered, and composed. We envision a future where:

Anyone can create and share tools that extend AI capabilities
Everyone has access to a rich ecosystem of tools regardless of their technical background
Every system can integrate with this ecosystem through standard protocols

🚀 Getting Started

Installation

npm install -g blah-mcp

Basic Usage

# Search for tools
blah search "image generation"

# Install a tool
blah install awesome-image-generator

# List installed tools
blah list

# Get info about a tool
blah info awesome-image-generator

📖 Core Concepts

The Registry

BLAH's registry is designed with lessons learned from package managers like npm, focusing on:

Transparency: All infrastructure code is open-source
Decentralization: Storage options include local, cloud, IPFS, or gists
Security: Optional signing of MCP servers with verification
Governance: Community-driven with no single entity controlling the ecosystem

Agent Behavior

BLAH supports various agent interaction patterns:

Parallel execution
Recursive tool calls
Branching workflows
Sequential processing
Complex graph-based workflows

Tool Definition

A tool in BLAH is fundamentally a function, but can be represented as:

Code snippets
RESTful endpoints
Local executables
Standard manifests (SLOP, agents.json)

Every tool should explicitly document how it's invoked, though this isn't mandatory.

🛠️ CLI Commands

BLAH comes with a comprehensive CLI:

blah publish    - Publish a tool to the registry
blah search     - Search for tools by name, tag, or description
blah install    - Install a tool
blah remove     - Remove an installed tool
blah update     - Update tools to latest versions
blah list       - List installed tools
blah info       - Display information about a tool
blah config     - Configure BLAH settings
blah login      - Authenticate with registry
blah logout     - End authentication session
blah whoami     - Show current authenticated user
blah version    - Display version information
blah help       - Show help information

📋 Manifests

BLAH uses a manifest file (blah.json) to define tools and their dependencies. This manifest can exist:

In a project workspace
In the home directory
Hosted in the cloud
As a gist or on IPFS

Example blah.json:

{
  "name": "awesome-image-generator",
  "version": "1.0.0",
  "description": "Tool for generating awesome images",
  "entry": "./dist/index.js",
  "tools": [
    {
      "name": "generate_image",
      "description": "Generates an image from a text prompt",
      "parameters": {
        "prompt": {
          "type": "string",
          "description": "Text description of the desired image"
        },
        "style": {
          "type": "string",
          "enum": ["realistic", "cartoon", "abstract"],
          "default": "realistic"
        }
      }
    }
  ],
  "dependencies": {
    "image-gen-lib": "^2.0.0"
  },
  "tags": ["image", "generation", "creative"]
}

🔄 Standards Support

BLAH supports and aims to be compatible with:

Model Context Protocol (MCP)
SLOP (Structure for Language Operator Protocols)
agents.json
[Your own custom protocols through converters]

🌟 Discovery and Metadata

Tools in BLAH are organized using:

Tags (e.g., #TOOLBELT)
Semantic metadata for intuitive navigation
Usage analytics for popularity-based recommendations
User-based recommendations (tools used by similar users)

🏗️ Architecture

BLAH consists of three main components:

Registry: For tool storage and discovery
CLI: For interacting with the registry and managing tools
MCP Server: For executing tools within agent workflows

Currently, ValTown serves as the primary backend for registry storage and compute, though alternative implementations are welcome.

🔒 Security & Accountability

BLAH takes security seriously:

Optional signing of MCP servers
Code execution in sandboxed environments
Comprehensive logging for accountability
Compliance with local laws and regulations

🚧 Roadmap

Host the MCP server on cloud platforms (e.g., Cloudflare Workers)
Create a web-based tool explorer and documentation site
Improve debugging and developer experience
Develop a tool creation wizard/generator
Implement tool recommendation system

🧠 Future Ideas

User behavior sharing for personalized tool recommendations
Scheduled agent execution through cron-like mechanisms
Decentralized governance model for registry management
Extension ecosystem for custom registry implementations

🤝 Contributing

Contributions are welcome! Check back soon for detailed contribution guidelines.

👏 Credits

Special thanks to Lisa and Wombat for their invaluable contributions to this project.

📄 License

BLAH is released under the MIT License. See the LICENSE file for details.

Build Logical Agents, Humanely