Add Haunt MCP (resolves #233 — conflict resolved) #288
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,46 @@ | ||
| { | ||
| "name": "haunt-mcp", | ||
| "description": "Adds Haunt MCP web extraction: permitted public URL to clean JSON, Markdown, article fields, metadata, and usage checks.", | ||
| "version": "1.0.23", | ||
| "author": { | ||
| "name": "Haunt API", | ||
| "email": "support@hauntapi.com", | ||
| "url": "https://hauntapi.com" | ||
| }, | ||
| "homepage": "https://hauntapi.com", | ||
| "repository": "https://github.com/Darko893/mcp-server", | ||
| "license": "MIT", | ||
| "keywords": [ | ||
| "mcp", | ||
| "web-extraction", | ||
| "structured-data", | ||
| "markdown", | ||
| "claude", | ||
| "cursor", | ||
| "codex", | ||
| "opencode", | ||
| "ai-agent" | ||
| ], | ||
| "skills": "./skills/", | ||
| "mcpServers": "./.mcp.json", | ||
| "interface": { | ||
| "displayName": "Haunt MCP", | ||
| "shortDescription": "Extract permitted public pages to JSON or Markdown from Codex.", | ||
| "longDescription": "Haunt gives Codex an MCP web-extraction tool for permitted public pages. Use a no-key demo first, then add HAUNT_API_KEY for live URL-to-JSON, Markdown, article, metadata, and usage tools with clear blocked-page errors.", | ||
| "developerName": "Haunt API", | ||
| "category": "Tools & Integrations", | ||
| "capabilities": [ | ||
| "mcp", | ||
| "web-extraction", | ||
| "structured-data", | ||
| "markdown" | ||
| ], | ||
| "websiteURL": "https://hauntapi.com", | ||
| "privacyPolicyURL": "https://hauntapi.com/privacy", | ||
| "termsOfServiceURL": "https://hauntapi.com/terms", | ||
| "brandColor": "#39ff88", | ||
| "defaultPrompt": [ | ||
| "Use Haunt to run try_demo_extract and show me the docs and signup links." | ||
| ] | ||
| } | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,5 @@ | ||
| .git/ | ||
| node_modules/ | ||
| *.tgz | ||
| .env | ||
| .env.* |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,14 @@ | ||
| { | ||
| "mcpServers": { | ||
| "haunt": { | ||
| "command": "npx", | ||
| "args": [ | ||
| "-y", | ||
| "@hauntapi/mcp-server" | ||
| ], | ||
| "env": { | ||
| "HAUNT_API_KEY": "${HAUNT_API_KEY}" | ||
| } | ||
| } | ||
| } | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,21 @@ | ||
| MIT License | ||
|
|
||
| Copyright (c) 2026 Haunt API | ||
|
|
||
| Permission is hereby granted, free of charge, to any person obtaining a copy | ||
| of this software and associated documentation files (the "Software"), to deal | ||
| in the Software without restriction, including without limitation the rights | ||
| to use, copy, modify, merge, publish, distribute, sublicense, and/or sell | ||
| copies of the Software, and to permit persons to whom the Software is | ||
| furnished to do so, subject to the following conditions: | ||
|
|
||
| The above copyright notice and this permission notice shall be included in all | ||
| copies or substantial portions of the Software. | ||
|
|
||
| THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR | ||
| IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, | ||
| FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE | ||
| AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER | ||
| LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, | ||
| OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE | ||
| SOFTWARE. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,138 @@ | ||
| # Haunt API MCP Server | ||
|
|
||
| This is the canonical public MCP package working tree for `@hauntapi/mcp-server` and GitHub `Darko893/mcp-server`. The live Haunt API app/site lives separately in `/root/haunt`. Do not confuse this with `/root/haunt/mcp-server`, which is a legacy/local copy inside the app repo. | ||
|
|
||
| Give Claude, Cursor, Windsurf, and other MCP-compatible agents a clean web extraction tool. | ||
|
|
||
| Haunt turns permitted public web pages into structured JSON using natural-language prompts. It can also return clean Markdown for agents, RAG pipelines, notes, and `.md` files when you need page text instead of typed fields. It is built for agent workflows that need product data, competitor pricing, article content, metadata, lead lists, research snippets, Markdown page text, or other visible web data without maintaining brittle selectors. | ||
|
|
||
| ## Quick Start | ||
|
|
||
| ### One-command agent setup | ||
|
|
||
| For the clean CLI path, run: | ||
|
|
||
| ```bash | ||
| npx -y --package @hauntapi/cli@latest haunt-cli init | ||
| ``` | ||
|
|
||
| If you already have a Haunt API key: | ||
|
|
||
| ```bash | ||
| HAUNT_API_KEY=PASTE_YOUR_KEY_HERE npx -y --package @hauntapi/cli@latest haunt-cli init | ||
| ``` | ||
|
|
||
| The CLI prints the MCP config for Claude, Cursor, Windsurf, and other MCP-compatible clients. It does not edit config files for you. | ||
|
|
||
| ### 1. Prove the MCP package is wired in, no key needed | ||
|
|
||
| Install the MCP server and call `try_demo_extract` first. It returns a fixed sample extraction JSON/trace plus docs, signup, pricing, and free-tier links without using credits. | ||
|
|
||
| ```text | ||
| Use Haunt's try_demo_extract tool and show me the signup and docs links. | ||
| ``` | ||
|
|
||
| ### 2. Add a free API key for live extraction | ||
|
|
||
| Get a free API key: https://hauntapi.com/#signup | ||
|
|
||
| Add this to your MCP client config: | ||
|
|
||
| ```json | ||
| { | ||
| "mcpServers": { | ||
| "haunt": { | ||
| "command": "npx", | ||
| "args": ["-y", "@hauntapi/mcp-server"], | ||
| "env": { | ||
| "HAUNT_API_KEY": "your-api-key" | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| Then ask your agent: | ||
|
|
||
| ```text | ||
| Use Haunt to extract the product name, price, availability, and review count from https://example.com/product | ||
| ``` | ||
|
|
||
| For Markdown output: | ||
|
|
||
| ```text | ||
| Use Haunt extract_markdown to turn https://example.com/docs into clean Markdown. | ||
| ``` | ||
|
|
||
|
|
||
| ## Capability boundaries | ||
|
|
||
| Haunt does **not** promise universal extraction, CAPTCHA solving, login-wall access, paywall access, or anti-bot circumvention. It works best on permitted public pages and supported rendered pages. When a page is blocked, login-required, CAPTCHA-gated, or too thin to verify, Haunt returns a clear failure signal instead of fabricated data. | ||
|
|
||
| ## Tools | ||
|
|
||
| ### `try_demo_extract` | ||
|
|
||
| No-key activation check. Returns a fixed sample extraction JSON/trace, Haunt's demo endpoint, docs, signup, pricing, MCP info route, and free-tier details. Use this first when a user has installed the MCP server but has not added `HAUNT_API_KEY` yet. | ||
|
|
||
| ### `extract` / `extract_url` | ||
|
|
||
| General-purpose extraction from permitted public web pages. `extract` and `extract_url` are aliases so hosted MCP docs and local stdio package users can follow the same wording. | ||
|
|
||
| Use it for: | ||
|
|
||
| - Product names, prices, stock status, reviews | ||
| - Competitor pricing pages | ||
| - Directories and lead lists | ||
| - Job boards | ||
| - Research pages | ||
| - Supported permitted public pages where you want clean JSON instead of HTML | ||
|
|
||
| It accepts optional `response_format` values: `json` (default), `markdown` / `md`, and `raw_html` / `html`. | ||
|
|
||
| ### `extract_markdown` | ||
|
|
||
| Return clean Markdown from a permitted public page. Use this when the agent or workflow wants readable page text for RAG, notes, docs ingestion, or saving as a `.md` file instead of structured fields. | ||
|
|
||
| ### `extract_article` | ||
|
|
||
| Extract article fields from news, blog, and editorial pages. | ||
|
|
||
| Returns title, body text, author, and publish date when available. | ||
|
|
||
| ### `extract_metadata` | ||
|
|
||
| Extract page metadata including title, description, Open Graph tags, Twitter Card tags, canonical URL, and related metadata. | ||
|
|
||
| ### `get_usage` | ||
|
|
||
| Check current plan, monthly credit limit, used credits, reserved credits, and remaining credits. Use this after a live extraction to see what was charged. | ||
|
|
||
| ## Why Haunt | ||
|
|
||
| - Natural-language prompts instead of fragile CSS selectors | ||
| - Supported fetch paths for JavaScript-heavy pages | ||
| - Challenge-aware extraction with machine-readable verification signals (`error_code`, `captcha_provider`, `requires_human_verification`) | ||
| - Clean JSON output for agents, databases, and workflows | ||
| - Clean Markdown output when the job is page text for agents, RAG, notes, or `.md` files | ||
| - Free tier for testing | ||
|
|
||
| ## Pricing | ||
|
|
||
| | Plan | Credits | Price | | ||
| |------|---------|-------| | ||
| | Free | 1,000/mo | £0 | | ||
| | Starter | 10,000/mo | £19/mo | | ||
| | Pro | 30,000/mo | £49/mo | | ||
| | Scale | 80,000/mo | £99/mo | | ||
|
|
||
| Credits are not one-to-one requests. Simple public/non-LLM output usually uses 1 credit, normal structured extraction 2, browser-rendered or authenticated extraction 4, and heavy/screenshot extraction 8. Failed, blocked, login/CAPTCHA, provider, and server failures do not burn credits. | ||
|
|
||
| Upgrade: https://hauntapi.com/#pricing | ||
|
|
||
| ## Links | ||
|
|
||
| - Website: https://hauntapi.com | ||
| - Docs: https://hauntapi.com/docs | ||
| - Get API key: https://hauntapi.com/#signup | ||
| - GitHub: https://github.com/Darko893/mcp-server |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,7 @@ | ||
| # Security Policy | ||
|
|
||
| Report security issues privately to support@hauntapi.com. | ||
|
|
||
| Do not open public issues containing secrets, API keys, customer data, exploit details, or private URLs. | ||
|
|
||
| Haunt is designed for permitted public pages and supported rendered pages. It does not promise CAPTCHA solving, login-wall access, paywall access, restricted-page access, or anti-bot circumvention. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,54 @@ | ||
| { | ||
| "name": "@hauntapi/mcp-server", | ||
| "version": "1.0.23", | ||
| "mcpName": "com.hauntapi/haunt", | ||
| "description": "MCP web extraction for permitted public pages: no-key demo plus live URL-to-JSON and Markdown output with honest blocked-page errors", | ||
| "main": "index.js", | ||
| "type": "module", | ||
| "bin": { | ||
| "mcp-server": "index.js", | ||
| "haunt-mcp": "index.js" | ||
| }, | ||
| "files": [ | ||
| "index.js", | ||
| "README.md", | ||
| "LICENSE", | ||
| "server.json", | ||
| "glama.json" | ||
| ], | ||
| "scripts": { | ||
| "start": "node index.js", | ||
| "test": "node --test" | ||
| }, | ||
| "keywords": [ | ||
| "mcp", | ||
| "mcp-server", | ||
| "model-context-protocol", | ||
| "claude", | ||
| "cursor", | ||
| "ai-agent", | ||
| "web-scraping", | ||
| "web-extraction", | ||
| "data-extraction", | ||
| "structured-data", | ||
| "markdown", | ||
| "markdown-extraction", | ||
| "clean-failure", | ||
| "scraper-api", | ||
| "json-extraction", | ||
| "javascript-rendering", | ||
| "challenge-aware", | ||
| "honest-failure" | ||
| ], | ||
| "author": "Haunt API", | ||
| "license": "MIT", | ||
| "repository": { | ||
| "type": "git", | ||
| "url": "git+https://github.com/Darko893/mcp-server.git" | ||
| }, | ||
| "dependencies": {}, | ||
| "homepage": "https://hauntapi.com", | ||
| "bugs": { | ||
| "url": "https://github.com/Darko893/mcp-server/issues" | ||
| } | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,31 @@ | ||||||
| --- | ||||||
| name: haunt-web-extraction | ||||||
| description: Use Haunt MCP to extract structured JSON, clean Markdown, article fields, metadata, or usage from permitted public web pages. | ||||||
| disable-model-invocation: true | ||||||
|
Contributor
There was a problem hiding this comment. Setting
Suggested change
|
||||||
| --- | ||||||
|
|
||||||
| # Haunt Web Extraction | ||||||
|
|
||||||
| Use this skill when the user needs data from a permitted public web page inside Claude Code, Cursor, Codex, OpenCode, or another MCP-aware coding agent. | ||||||
|
|
||||||
| ## First action | ||||||
|
|
||||||
| If the Haunt MCP server is installed but no API key is configured yet, call `try_demo_extract` first. It proves the server is wired correctly and returns docs, signup, pricing, MCP info, and free-tier links without using credits. | ||||||
|
|
||||||
| ## Live extraction | ||||||
|
|
||||||
| For live pages, require `HAUNT_API_KEY` in the MCP server environment. Use: | ||||||
|
|
||||||
| - `extract_url` or `extract` for structured JSON from a permitted public URL. | ||||||
| - `extract_markdown` for readable page text for RAG, notes, docs ingestion, or `.md` files. | ||||||
| - `extract_article` for public article pages. | ||||||
| - `extract_metadata` for titles, descriptions, Open Graph, Twitter Card, and canonical URL metadata. | ||||||
| - `get_usage` after live calls to check plan and remaining credits. | ||||||
|
|
||||||
| ## Boundaries | ||||||
|
|
||||||
| Haunt is for permitted public pages and supported rendered pages. It does not promise CAPTCHA solving, login-wall access, paywall access, restricted-page access, or anti-bot circumvention. If a page is blocked, login-required, CAPTCHA-gated, paywalled, restricted, or too thin to verify, treat Haunt's clear failure signal as the correct result. Do not fabricate extracted data. | ||||||
|
|
||||||
| ## Good prompt pattern | ||||||
|
|
||||||
| "Use Haunt to extract the product name, price, availability, and review count from this permitted public URL: <url>. Return JSON and tell me if the page was blocked or unverifiable." | ||||||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The
namefield in the marketplace entry should match the plugin's identifier in itsplugin.json(which is"haunt-mcp"). Using"Haunt MCP"with spaces and capital letters will cause a mismatch and may break plugin installation or resolution. The user-facing name should be specified indisplayNameinstead.