aidefend-mcp - AIDEFEND MCP is a local-first AI Security Defensiv

项目说明

English README | 繁體中文 README

---

AIDEFEND MCP / REST API Service

![CI]()
![License: MIT]()
![Python 3.10-3.14]()
![FastAPI]()

Local retrie for the AIDEFEND framework.

This repository safely parses the framework's Ja tactics, builds a local LanceDB knowledge base, and exposes the result through:

a REST API for applications and automation

an MCP server for AI assistants such as Claude Desktop

This repository is not the framework itself. It is the service layer on top of the framework.

What You Get

Local semantic search o content

REST API and MCP access from the same indexed knowledge base

Automatic sync from the upstream GitHub repository by default

Optional local framework o for contributors working on both repos

Multilingual embedding search with Xeno

Automated tests and Bandit security scanning in GitHub Actions

How It Works

1. Sync AIDEFEND tactic files from GitHub.
2. Parse the Ja files with a Node.js AST parser. The service does not execute upstream framework code.
3. Expand tactics into techniques, sub-techniques, and strategies.
4. Generate embeddings and store the documents in LanceDB.
5. Serve the indexed data over REST or MCP.

Rolling Framework Compatibility

The current release snapshot is AIDEFEND 1.20260911 with public
schema 2.3 and MCP index schema 3.3. It includes all three framework
tool categories: open-source,
source-a/open-weight, and commercial. Snapshot IDs, titles, counts,
and ordering are examples of what was for this release, not
permanent runtime constraints.

Within the supported framework contract, synchronization dynamically rebuilds
both the MCP and REST data from the selected source. Content additions and
removals, ID renumbering, title or guidance edits, count and order changes, and
compatible additi do not require customer-specific configuration.
Source-defined threat-framework labels are also carried through co and
analytics instead of being limited to the exact label set in this snapshot.
When a supported framework is renamed again, its acti becomes the
display name while every declared edition label remains an input alias for the
same stable API key. Cross-framework label collisions, mismatched active
edition labels, and malformed multi-word item identifiers are rejected during
sync rather than guessed.
Exact scope-boundary and tool remain a as structured MCP/REST
metadata even if unusually long content exceeds the embedding model's
searchable token window; that condition is warned about rather than rejecting
an otherwise valid update.

Framework-edition migrations are synchronized from
data/framework-migrations.json in the same immutable source snapshot. The
acti LLM edition is 2026. Bare IDs and latest references resolve
to that edition; an explicit 2025 ID is migrated by its declared semantic
successor, never by reusing the same rank. Responses expose the canonical 2026
ID and structured resolution metadata. Unsupported or genuinely ambiguous
references fail closed without running a threat lookup. The registry
and index pro are committed together in the atomically replaced
metadata, so a failed update cannot pair a new resol with an older
database.

Cisco references use the acti synchronized with that same index;
the current Framework supplies v2.0.0. Compatible catalog label, edition
and population changes are from metadata rather than pinned to this
release's 156 items. Bare IDs resolve to the acti. Superseded editions,
retired IDs and ID/name conflicts return diagnostics without carrying old mappings
forward. Other catalog profiles can remain a for ingestion and co;
an unsupported reference format returns an explicit resol.

To activate this update, update the MCP code/package used by your client and
synchronize the newly published Framework. Existing processes must restart to load
new code. For an explicit python __main__.py --resync, first stop the service
owning that DATA_PATH, wait for synchronization to finish, then restart it.
Pushing either repository alone does not update an already installed MCP package
or prove that its index has synchronized.

The Framework Public Schema is discovered dynamically from the root
.schema value in data/data.json. Local-source mode reads that
file from the same configured framework root as the tactics; GitHub mode reads
it from the exact immutable commit used for those tactics, ne
from a floating branch. This public dataset is used only for schema metadata
discovery and is not indexed a second time or substituted for the tactic
authoring sources. Missing or invalid metadata safely reports the public schema
as una without guessing or weakening the full parser and index
gates.

With automatic sync enabled (the default), the service checks once at startup
and then every SYNC_INTER seconds: 3600 by default, configurable
from 60 to 86400. Repeated failures use backoff. Separately, a rolling daily
upstream canary exercises the latest public framework in addition to the exact
release snapshot.

The service does not claim automatic compatibility with arbitrary breaking
schema changes. Every candidate index is before acti. If an
upstream source is invalid or genuinely incompatible, an existing installation
keeps serving its last-known-good index through MCP and REST and reports the
sync error. metadata is written by atomic replacement; if that final
commit fails after database acti, the uncommitted database is taken
offline and the last-known-good database is restored when one exists. A clean
installation without a index fails explicitly instead of publishing
partial or misinterpreted data; support for a new breaking contract must be
released deliberately.
For example, a fourth semantic tool category or a changed field shape is
treated as a breaking contract and rejected rather than silently discarded.

Requirements

Python 3.10 to 3.14

Node.js 18+

Git

About 2 to 3 GB free disk space for dependencies, embedding model, and local database

npm is not required for installation or runtime. The Acorn parser is bundled
in /; Node.js 18+ is the only Ja runtime prerequisite.

Normal users do not need to configure any personal local path. The default setup syncs from GitHub.

Quick Start

1. Clone the repository

2. Pick an installation path

| Use case | Recommended command |
| --- | --- |
| Claude Desktop MCP | python scripts/install.py |
| Claude Code MCP | python scripts/install.py --client code |
| REST API only | python scripts/install.py --no-mcp |
| Manual setup | Follow INSTALL.md |

3. Build the local knowledge base

The first sync downloads the framework, embedding model, and creates the local database. Expect several minutes on a clean machine.

4. Run the service

REST API:

MCP server:

Choose one runtime for each data directory. A REST process, stdio MCP process,
--resync command, or maintenance command must ha ownership of its
configured DATA_PATH. To run REST and MCP at the same time, configure separate
data directories and keep each instance's DB_PATH, RAW_PATH, and
with that instance; do not share any of those paths.

Health check:

Data-directory lock and upgrades

DATA_PATH/sync.lock is a persistent rendezvous file for the operating-system
lock. The file may remain after a clean shutdown; its presence or age is not
e that the lock is active. Do not delete or replace it to force another
service or resync to start. Stop the process that owns the data directory, or
use a different complete set of storage paths.

Before upgrading from a release that did not hold this lock for the complete
service lifetime, stop every REST service, close MCP clients that launch the
stdio server, and let all resync or maintenance commands finish. Then upgrade
and start one owner for each DATA_PATH.

Manual Setup From a Fresh Clone

If you want a clean, explicit install path instead of the helper script:

Activate the en.

Windows PowerShell:

macOS/Linux:

Install dependencies:

The secure Ja parser uses the Acorn runtime bundled in /, so
this setup does not download Node packages or require npm.

Create local config:

macOS/Linux:

Windows PowerShell:

Then run:

Optional Local Framework O

By default the service syncs from GitHub. If you are de this repo alongside a local checkout of aidefense-framework, you can point the sync to your local source:

This is optional and should stay unset for normal open-source users.

Common Commands

Docker

The container binds 0.0.0.0, so authentication is required — set an API key before starting:

Use one service replica per writable data . Horizontal scaling requires
an independent data copy or for every replica, or an external data layer
designed for concurrent clients; the bundled local LanceDB directory must not
be shared by multiple replicas.

See docs/CONFIGURATION.md for auth details.

Documentation

Installation: INSTALL.md

Configuration: docs/CONFIGURATION.md

Ad configuration: docs/AD.md

Tool reference: docs/TOOLS.md

Security notes: SECURITY.md

Changelog: CHANGELOG.md

Repository Notes

data/, local caches, co output, and .env are ignored by git and are not required in the repository.

A source checkout stores runtime data under data/. An installed wheel uses

the OS per-user application-data directory; Docker uses /app/data.

One DATA_PATH supports one REST, MCP, resync, or maintenance process at a

time. Concurrent modes or replicas require independent storage.

CI builds and a li index, exercises all 18 MCP and 18

REST tool paths from both the source checkout and an externally installed
wheel on Linux, and runs clean-wheel install/parser/console checks on
Windows, macOS, and Linux across Python 3.10-3.14. A release is not ready
until that hosted matrix passes. Bandit and a real
container build/runtime contract run alongside the daily rolling-upstream
canary and framework release dispatches.

The source contract discovers the ordered tactic set from the framework's

main.js manifest, including parent/shared mappings, actionable
sub-techniques, warnings, and implementation guidance.

License and Framework Content

The AIDEFEND MCP Service source code is licensed under the MIT License. See
LICENSE.

The framework content downloaded, indexed, and returned by this service keeps
its own license:

> AIDEFEND AI Defense Framework, created by Edward Lee,
> licensed under CC BY 4.0.

Framework software is Apache-2.0, framework content/data is CC BY 4.0, and
trademark rights are not granted. See THIRD_PARTY_CONTENT.md
and the framework repository's licensing files for details. The synchronized
edition-migration registry also carries source-specific attribution and
CC BY-SA 4.0 terms for its normalized OWASP-deri, names,
metadata, and summaries; those terms are recorded in the registry itself.

项目信息

开发语言：Python

Star 数：18

技术要点

该项目属于防护思路方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕AIDEFEND MCP is a local-first AI Security Defensive Assistant that brings the full AIDEFEND countermeasure library into your environment and turns static knowledge into actionable protection for LLMs and agentic AI systems — privately, securely, and on-device.展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。