Skip to content

INSTALL.md

Latest commit

 

History

History
206 lines (139 loc) · 4.23 KB

INSTALL.md

File metadata and controls

206 lines (139 loc) · 4.23 KB
Raw

Install and Deploy Guide

Copyright (c) 2026 Ascent Partners Foundation. MIT License.

Prerequisites

Requirement Minimum version Install
Node.js 20.x LTS or later nodejs.org/download
pnpm 10.x or later npm install -g pnpm
Git Any recent version git-scm.com
Docker 24.x or later (optional) docs.docker.com/get-docker

Option A — Local install (Node + pnpm)

1. Clone the repository

git clone https://github.com/humanity4ai/project_human.git
cd project_human

2. Install dependencies

pnpm install

3. Verify the install

pnpm check   # TypeScript type checks
pnpm evals   # Skill quality gates (all 11 should pass)

Expected output:

PASS  wcag-aaa-accessibility
PASS  depression-sensitive-content
...
PASS  contract-consistency

All 11 checks passed.

4. Start the MCP server

pnpm start

The server will print a startup banner to stderr:

Humanity4AI MCP Server v0.1.0
Actions: 10 registered
Transport: stdio (MCP JSON-RPC 2.0)
Ready

5. Send your first request

Open a second terminal and run:

echo '{"id":"1","type":"list_actions"}' \
  | pnpm --filter @humanity4ai/mcp-servers exec tsx src/mcp-server.ts

You should receive a JSON response listing all 10 registered actions.

6. Invoke a skill

echo '{"id":"2","type":"invoke","payload":{"action":"supportive_reply","input":{"message":"I feel overwhelmed","risk_level":"medium"}}}' \
  | pnpm --filter @humanity4ai/mcp-servers exec tsx src/mcp-server.ts

Option B — Docker (recommended for production)

Docker requires no Node.js install on the host machine.

1. Clone the repository

git clone https://github.com/humanity4ai/project_human.git
cd project_human

2. Start with Docker Compose

docker compose up --build

3. Send a request to the running container

echo '{"id":"1","type":"list_actions"}' \
  | docker compose exec -T mcp-server node dist/mcp-server.js

4. Run in background

docker compose up --build -d

5. Stop

docker compose down

Option C — npm package install

For integrating the MCP contracts and handlers into your own project:

pnpm add @humanity4ai/mcp-servers
# or
npm install @humanity4ai/mcp-servers

Then import contracts:

import { actionContracts, validateContracts } from "@humanity4ai/mcp-servers";
import { invokeAction } from "@humanity4ai/mcp-servers/handlers";

const result = invokeAction("supportive_reply", {
  message: "I feel overwhelmed",
  risk_level: "medium"
});

if (result.ok) {
  console.log(result.data.output);
}

Environment variables

Variable Default Description
EVAL_REPORT 0 Set to 1 to write a markdown report to evals/reports/latest.md
NODE_ENV development Set to production for production deployments

Troubleshooting

pnpm: command not found

Install pnpm globally:

npm install -g pnpm

error TS... on pnpm check

Ensure you are using Node.js >= 20:

node --version  # should be v20.x or higher

Server starts but returns no output

The server reads from stdin and writes to stdout. Pipe your request correctly:

echo '{"id":"1","type":"list_actions"}' | pnpm start

Do not run pnpm start interactively without piping input — it will wait silently.

Docker: port already in use

The MCP server uses stdin/stdout only — no TCP ports are exposed. This error is unrelated to Humanity4AI. Check for port conflicts in your docker-compose.yml if you have added custom services.

Verify everything works

Run this checklist before deploying to any environment:

pnpm install           # Dependencies installed
pnpm check             # TypeScript passes
pnpm build             # Package builds cleanly
pnpm evals             # All 11 quality gates pass
echo '{"id":"1","type":"list_actions"}' | pnpm --filter @humanity4ai/mcp-servers exec tsx src/mcp-server.ts
# Should return JSON with 10 actions